# MCP Platform — Third-Party Integration Roadmap

## Overview

The MCP platform is a production-grade AI orchestration server built on Elixir/OTP. It exposes 50+ MCP tools for AI agents, provides REST APIs and web UIs, and supports real-time WebSocket communication. This roadmap outlines the strategy for integrating third-party business services — enabling AI agents to orchestrate cross-platform workflows through natural language.

---

## Current Capabilities

| Category | Features |
|---|---|
| **AI Chat** | Multi-LLM support (Claude, Grok, Perplexity), runtime provider switching, per-user sessions with tool use |
| **Task Management** | Full lifecycle with 60+ query functions, subtasks, priorities, tags, timezone-aware scheduling |
| **WhatsApp** | Send/receive text and media, contacts, groups, message history via Node.js + ZeroMQ bridge |
| **Blog & Content** | WYSIWYG editor, semantic vector search (sqlite-vec), chunked embeddings, public reader |
| **Article Summaries** | URL summarization via configurable LLM, vector semantic search, Chrome extension trigger |
| **Access Control** | Permission keys, role-based access, TTL grants, AES-256 encrypted roles, full audit trail |
| **Scheduling** | Natural language time parsing, persistent alarms, Pushover push notifications |
| **A2A Protocol** | Google Agent-to-Agent discovery and task orchestration |
| **Monitoring** | System health, process tree, database stats, service status via REST API |

---

## Integration Architecture

Every third-party integration follows the same proven 4-layer pattern:

```
┌─────────────────────────────────────────────────┐
│                   AI Agent / Chat                │
│          (Claude, Grok, Perplexity, etc.)        │
└──────────────────────┬──────────────────────────┘
                       │ MCP tool calls
┌──────────────────────▼──────────────────────────┐
│              MCP Tool Definitions                │
│      (permission-gated, JSON schema inputs)      │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│            Service Wrapper (GenServer)            │
│   (singleton process, OTP-supervised, auto-restart)│
└──────────────────────┬──────────────────────────┘
                       │ HTTP / SDK
┌──────────────────────▼──────────────────────────┐
│             Third-Party API                      │
│      (Salesforce, ServiceNow, Tableau, etc.)     │
└─────────────────────────────────────────────────┘
```

**Each layer is optional except the service wrapper.** A minimal integration is ~200 lines. A full integration with REST API, web UI, caching, and multiple tools is ~400-600 lines.

---

## Phase 1 — CRM & Sales (Salesforce)

### Objective

Enable AI agents to query, create, and update Salesforce records. Sales teams can ask questions in natural language and get live CRM data.

### MCP Tools

| Tool | Description | Permission |
|---|---|---|
| `salesforce_query` | Run SOQL queries against any Salesforce object | view |
| `salesforce_get_record` | Get a single record by ID and object type | view |
| `salesforce_create` | Create a new record (Account, Contact, Opportunity, etc.) | admin |
| `salesforce_update` | Update fields on an existing record | admin |
| `salesforce_opportunities` | List opportunities with filters (stage, close date, amount) | view |
| `salesforce_search` | Full-text search across all objects (SOSL) | view |

### REST API Endpoints

```
GET    /api/salesforce/query?soql=...
GET    /api/salesforce/records/:object/:id
POST   /api/salesforce/records/:object
PUT    /api/salesforce/records/:object/:id
GET    /api/salesforce/opportunities?stage=...&min_amount=...
GET    /api/salesforce/search?q=...
```

### Authentication

- OAuth 2.0 JWT Bearer flow (server-to-server, no user interaction)
- Credentials stored in environment variables: `SALESFORCE_INSTANCE_URL`, `SALESFORCE_CLIENT_ID`, `SALESFORCE_PRIVATE_KEY`
- Token refresh handled automatically by the GenServer

### Example AI Workflow

> "Find all Salesforce opportunities closing this month over $50k and summarize them"

The AI chains: `salesforce_opportunities` → formats results → returns summary.

---

## Phase 2 — IT Service Management (ServiceNow)

### Objective

Automate incident management, change requests, and CMDB queries. IT teams can create and resolve tickets through AI conversation.

### MCP Tools

| Tool | Description | Permission |
|---|---|---|
| `servicenow_create_incident` | Create a new incident with category, priority, description | admin |
| `servicenow_get_incident` | Get incident details by number (e.g., INC0012345) | view |
| `servicenow_update_incident` | Update incident fields (state, assignment, notes) | admin |
| `servicenow_resolve_incident` | Resolve an incident with resolution notes | admin |
| `servicenow_query` | Query any ServiceNow table with encoded query string | view |
| `servicenow_cmdb_search` | Search Configuration Management Database | view |
| `servicenow_change_request` | Create a change request with risk/impact assessment | admin |

### REST API Endpoints

```
POST   /api/servicenow/incidents
GET    /api/servicenow/incidents/:number
PUT    /api/servicenow/incidents/:number
POST   /api/servicenow/incidents/:number/resolve
GET    /api/servicenow/query/:table?q=...
GET    /api/servicenow/cmdb/search?q=...
POST   /api/servicenow/change-requests
```

### Authentication

- OAuth 2.0 client credentials flow
- Environment variables: `SERVICENOW_INSTANCE`, `SERVICENOW_CLIENT_ID`, `SERVICENOW_CLIENT_SECRET`

### Example AI Workflow

> "Create a P2 incident for the payment gateway timeout we're seeing, assign it to the payments team, and post the incident number to #incidents in Slack"

The AI chains: `servicenow_create_incident` → `slack_send` (Phase 4).

---

## Phase 3 — Business Intelligence (Tableau)

### Objective

Enable AI agents to query Tableau dashboards, trigger data refreshes, and retrieve view data. Decision-makers can ask questions about their data in natural language.

### MCP Tools

| Tool | Description | Permission |
|---|---|---|
| `tableau_list_workbooks` | List all workbooks the service account can access | view |
| `tableau_list_views` | List views within a workbook | view |
| `tableau_view_data` | Get underlying data from a view with optional filters | view |
| `tableau_refresh_extract` | Trigger a data source extract refresh | admin |
| `tableau_refresh_status` | Check the status of a running refresh job | view |
| `tableau_download_pdf` | Export a view as PDF | view |

### REST API Endpoints

```
GET    /api/tableau/workbooks
GET    /api/tableau/workbooks/:id/views
GET    /api/tableau/views/:id/data?filters=...
POST   /api/tableau/datasources/:id/refresh
GET    /api/tableau/jobs/:id
GET    /api/tableau/views/:id/pdf
```

### Authentication

- Personal Access Token (PAT) or JWT (Connected App)
- Environment variables: `TABLEAU_SERVER_URL`, `TABLEAU_SITE_ID`, `TABLEAU_TOKEN_NAME`, `TABLEAU_TOKEN_SECRET`

### Example AI Workflow

> "Pull the latest revenue data from the Q1 dashboard and compare it with last quarter's Salesforce pipeline"

The AI chains: `tableau_view_data` → `salesforce_query` → compares and summarizes.

---

## Phase 4 — Communication & Collaboration

### Slack

| Tool | Description | Permission |
|---|---|---|
| `slack_send` | Send a message to a channel or user | admin |
| `slack_channels` | List channels | view |
| `slack_thread_reply` | Reply in a thread | admin |
| `slack_search` | Search message history | view |

### Microsoft Teams

| Tool | Description | Permission |
|---|---|---|
| `teams_send` | Send a message to a channel or chat | admin |
| `teams_channels` | List channels in a team | view |
| `teams_create_meeting` | Schedule a Teams meeting | admin |

### Email (SMTP / SendGrid / SES)

| Tool | Description | Permission |
|---|---|---|
| `email_send` | Send an email with subject, body, recipients | admin |
| `email_send_template` | Send a templated email | admin |

### Authentication

- Slack: Bot token via `SLACK_BOT_TOKEN`
- Teams: Azure AD app registration via `TEAMS_CLIENT_ID`, `TEAMS_CLIENT_SECRET`, `TEAMS_TENANT_ID`
- Email: SMTP credentials or API key via `EMAIL_API_KEY`

---

## Phase 5 — Project Management

### Jira

| Tool | Description | Permission |
|---|---|---|
| `jira_search` | Search issues with JQL | view |
| `jira_create` | Create an issue (story, bug, task, epic) | admin |
| `jira_update` | Update issue fields | admin |
| `jira_transition` | Move issue to a new status | admin |
| `jira_sprint_board` | Get current sprint with issue breakdown | view |
| `jira_add_comment` | Add a comment to an issue | admin |

### Asana / Monday.com

| Tool | Description | Permission |
|---|---|---|
| `asana_tasks` | List tasks in a project | view |
| `asana_create_task` | Create a task with assignee, due date, tags | admin |
| `asana_complete` | Mark a task complete | admin |

---

## Phase 6 — Data & Analytics

### Google Sheets / Excel Online

| Tool | Description | Permission |
|---|---|---|
| `sheets_read` | Read a range from a spreadsheet | view |
| `sheets_write` | Write data to a range | admin |
| `sheets_append` | Append rows to a sheet | admin |

### SQL Databases (Postgres, MySQL, SQL Server)

| Tool | Description | Permission |
|---|---|---|
| `sql_query` | Run a read-only SQL query against a configured database | view |
| `sql_describe` | Describe table schema | view |

### Snowflake / BigQuery

| Tool | Description | Permission |
|---|---|---|
| `warehouse_query` | Run a query against the data warehouse | view |
| `warehouse_tables` | List available tables and schemas | view |

---

## Phase 7 — Cloud Infrastructure

### AWS

| Tool | Description | Permission |
|---|---|---|
| `aws_ec2_instances` | List EC2 instances with status | view |
| `aws_s3_list` | List S3 bucket contents | view |
| `aws_cloudwatch_metrics` | Query CloudWatch metrics | view |
| `aws_lambda_invoke` | Invoke a Lambda function | admin |

### GCP / Azure

Follow the same pattern — service wrapper GenServer, MCP tools, permission-gated.

---

## Cross-Platform Workflow Examples

These workflows demonstrate the power of composable MCP tools. Once integrated, AI agents chain tools automatically — no custom workflow code required.

### Sales Pipeline Review

> "Show me all Salesforce opportunities closing this quarter over $100k, cross-reference with Jira to check if their implementation tickets are on track, and send a summary to #sales-leadership in Slack"

**Tool chain:** `salesforce_opportunities` → `jira_search` (loop) → `slack_send`

### Incident Response

> "There's a payment processing outage. Create a P1 incident in ServiceNow, post to #incidents in Slack, find the on-call engineer in our team schedule, and send them a Pushover notification"

**Tool chain:** `servicenow_create_incident` → `slack_send` → `pushover_send`

### Weekly Business Report

> "Pull this week's revenue from Tableau, get completed tasks from our task manager, summarize the top 5 blog posts by search volume, and email the report to the leadership team"

**Tool chain:** `tableau_view_data` → `task_query("completed_this_week")` → `blog_search` → `email_send`

### Customer Onboarding

> "A new customer signed up — create their account in Salesforce, set up a Jira project for implementation, create a shared Slack channel, and send them a welcome email"

**Tool chain:** `salesforce_create` → `jira_create` → `slack_create_channel` → `email_send_template`

---

## Implementation Checklist Per Integration

Each integration follows the same recipe:

- [ ] **Service module** — `lib/<service>.ex` GenServer wrapping the API
- [ ] **Supervision tree** — Add to `lib/mcp/application.ex` children list
- [ ] **MCP tools** — Definitions in `MyMCPServer.tool_definitions/0` + handler clauses
- [ ] **Permission keys** — Unique integer keys, `use AccessControlled`
- [ ] **REST API** (optional) — `lib/<service>_rest.ex` + routes in router
- [ ] **Local cache** (optional) — Sqler database for caching expensive API calls
- [ ] **Configuration** — Environment variables for credentials, documented in moduledoc
- [ ] **Error handling** — `{:ok, _} | {:error, _}` at all boundaries, timeouts on API calls
- [ ] **Testing** — MCP tool calls, REST endpoints, permission enforcement

### Estimated Effort Per Integration

| Complexity | Lines of Code | Examples |
|---|---|---|
| Simple (read-only, 2-3 tools) | ~200 | Google Sheets, Pushover |
| Medium (CRUD, 4-6 tools) | ~400 | Salesforce, Jira, ServiceNow |
| Complex (real-time, events, caching) | ~600+ | WhatsApp, Slack with events |

---

## Priority Matrix

| Priority | Integration | Business Value | Complexity |
|---|---|---|---|
| P1 | Salesforce | High — CRM is central to sales ops | Medium |
| P1 | ServiceNow | High — IT operations automation | Medium |
| P1 | Slack | High — team communication hub | Medium |
| P2 | Tableau | High — data-driven decisions | Medium |
| P2 | Jira | Medium — engineering workflow | Medium |
| P2 | Email (SendGrid/SES) | Medium — customer communication | Simple |
| P3 | Google Sheets | Medium — ad-hoc data management | Simple |
| P3 | Microsoft Teams | Medium — enterprise communication | Medium |
| P3 | Snowflake/BigQuery | High — analytics at scale | Medium |
| P4 | AWS/GCP/Azure | Situational — infrastructure ops | Complex |
| P4 | Asana/Monday | Low — overlaps with built-in tasks | Simple |

---

## Security Considerations

- **Credentials** are stored in environment variables, never in code or logs
- **Permission keys** are unique integers per tool — unauthorized users never see the tool exists
- **Audit trail** logs every tool invocation with user, timestamp, and parameters
- **OAuth tokens** are refreshed automatically by the service GenServer
- **Rate limiting** should be added per service to respect API quotas
- **Data filtering** — sensitive fields (SSN, credit card) should be stripped before returning to AI agents
- **Encrypted roles** — permission bundles are AES-256 encrypted at rest in SQLite

---

## Technical Prerequisites

| Requirement | Status |
|---|---|
| Elixir/OTP runtime | Deployed |
| HTTPS with TLS | Configured (port 8443) |
| SQLite + sqlite-vec | Installed |
| Req HTTP client | In deps |
| MCP protocol server | Running (Hermes) |
| Access control system | Production-ready |
| A2A agent discovery | Implemented |
| Monitoring API | Active |

No additional infrastructure is required. Each integration is a self-contained GenServer added to the existing supervision tree.