> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI clients and external agents to CRAFT's tool gateway over the Model Context Protocol — IDE integrations, headless agent access, and tool reference

# MCP Server

CRAFT handles the **"what"** — governed, accurate data retrieval from your enterprise systems — so your AI tools and agents can focus on the **"why"**: validating hypotheses, identifying root causes, running what-if scenarios, and surfacing anomalies. Use `resolve_term` so your agent knows what "active customer" means in *your* warehouse before generating SQL; use `execute_query` to validate results; use `generate_plotly_chart` to surface patterns instantly. Connect Claude Code, Cursor, Goose, or a purpose-built agent to `https://craft.emergence.ai/mcp` and CRAFT becomes a governed data layer for any reasoning workflow.

Two connection patterns: **(a) interactive** — IDE clients query CRAFT while you code; **(b) programmatic** — embed CRAFT as a tool server in an agent pipeline for hypothesis testing, root cause analysis, anomaly detection, or what-if modeling.

## Server details

| Property | Value |
| - | - |
| Endpoint | `https://craft.emergence.ai/mcp` |
| Transport | Streamable HTTP ([MCP 2025-11-25 spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports); SSE-compat path available) |
| Auth | OAuth 2.0 PKCE (authorization code + S256, via Keycloak) |
| Health | `GET https://craft.emergence.ai/health` → `{"status": "ok"}` |

## Verify the endpoint (no auth needed)

Before setting up OAuth, confirm the server is reachable with the no-auth `hello_world` tool:

```bash theme={null}
curl -s -X POST https://craft.emergence.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hello_world","arguments":{}}}' \
| jq .
```

Expected response:

```json theme={null}
{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "Hello from CRAFT MCP server"}]}}
```

If this succeeds, network connectivity and DNS are confirmed. If you prefer a CLI tool:

```bash theme={null}
npx @mcpjam/cli server doctor --url https://craft.emergence.ai/mcp
```

## Authentication

### Interactive clients (OAuth)

Supported IDE clients use the [MCP OAuth 2.0 PKCE authorization flow](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).

On first connection, the client opens a browser window to `craft.emergence.ai`, where you sign in with your **Google** or **Microsoft** account. The access token is stored and refreshed by the client automatically — no manual token handling required.

### X-Project-ID header

All tools except `hello_world` require an `X-Project-ID` header scoping the request to your CRAFT project. Find your project ID in the CRAFT console under **Settings → Project → ID**.

`X-Project-ID` selects a project scope but does **not** grant access — project membership is enforced server-side against your JWT's claims. Passing an arbitrary project ID returns an authorization error if you are not a member.

### Token requirements for headless callers

Programmatic callers (agents, pipelines) must obtain an access token before calling tools:

| Requirement | Value |
| - | - |
| Issuer (`iss`) | `https://craft.emergence.ai/keycloak/realms/emergence` |
| Required scopes | `openid profile email` |
| Grant type | Authorization code (interactive) or Client credentials (service account) |
| Token TTL | \~5 minutes; refresh token manages rotation for interactive clients |

For service accounts and CI pipelines, see [Service Accounts](https://docs.emergence.ai/platform/service-accounts.md) and [Authentication](https://docs.emergence.ai/platform/authentication.md).

## Connect your AI client

> [accordion] Claude Code
>
> Add the CRAFT MCP server from the CLI:
>
> ```bash theme={null}
> claude mcp add --transport http craft https://craft.emergence.ai/mcp \
>   --header "X-Project-ID: <your-project-id>"
> ```
>
> Or add it to `.mcp.json` in your project root (or `~/.claude.json` for user-scope):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "craft": {
>       "type": "http",
>       "url": "https://craft.emergence.ai/mcp",
>       "headers": {
>         "X-Project-ID": "<your-project-id>"
>       }
>     }
>   }
> }
> ```
>
> The OAuth browser flow triggers automatically on first tool call. Token refresh is handled by Claude Code.
>
> > [!NOTE]
> >
> > Find your project ID in the CRAFT console under **Settings → Project → ID**.

> [accordion] Cursor
>
> Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "craft": {
>       "type": "http",
>       "url": "https://craft.emergence.ai/mcp",
>       "headers": {
>         "X-Project-ID": "${env:CRAFT_PROJECT_ID}"
>       }
>     }
>   }
> }
> ```
>
> Set `CRAFT_PROJECT_ID` as a shell environment variable — Cursor expands `${env:VAR}` at runtime. The OAuth browser window opens on first use.

> [accordion] VS Code
>
> Create `.vscode/mcp.json` in your project:
>
> ```json theme={null}
> {
>   "inputs": [
>     {
>       "type": "promptString",
>       "id": "craft-project-id",
>       "description": "Your CRAFT project ID"
>     }
>   ],
>   "servers": {
>     "craft": {
>       "type": "http",
>       "url": "https://craft.emergence.ai/mcp",
>       "headers": {
>         "X-Project-ID": "${input:craft-project-id}"
>       }
>     }
>   }
> }
> ```
>
> VS Code prompts for the project ID once and stores it securely. OAuth handles the access token automatically.
>
> > [!WARNING]
> >
> > If tool calls fail silently, headers may not be forwarded — a known issue in some VS Code versions ([#264095](https://github.com/microsoft/vscode/issues/264095)). Workaround: replace the `type`/`url` block with `mcp-remote`:
> >
> > ```json theme={null}
> > {
> >   "servers": {
> >     "craft": {
> >       "command": "npx",
> >       "args": [
> >         "mcp-remote@latest",
> >         "https://craft.emergence.ai/mcp",
> >         "--header",
> >         "X-Project-ID: <your-project-id>"
> >       ]
> >     }
> >   }
> > }
> > ```
> >
> > Note: `mcp-remote` handles the OAuth flow locally rather than delegating it to the server.

> [accordion] Goose
>
> Add to `~/.config/goose/config.yaml`:
>
> ```yaml theme={null}
> extensions:
>   craft:
>     name: craft
>     type: http
>     url: https://craft.emergence.ai/mcp
>     enabled: true
>     headers:
>       X-Project-ID: "${CRAFT_PROJECT_ID}"
> ```
>
> Set `CRAFT_PROJECT_ID` in your environment. Alternatively, run `goose configure`, select **Remote Extension (Streamable HTTP)**, and the interactive wizard will prompt you for the URL and any custom headers. OAuth triggers on first connection.

## Interactive charts — MCP Apps extension

`generate_plotly_chart` returns both a raw `plotly_json` response (all clients) and an embedded interactive UI resource for clients that support the [MCP Apps protocol](https://modelcontextprotocol.io/extensions/apps/overview). The embedded resource is a sandboxed iframe containing the full Plotly chart with a modebar — including an **SVG download** button — rendered inline alongside the chat without switching tabs.

The interactive iframe is enabled by default (`MCP_APPS_ENABLED=true`). No client-side configuration is required; supported clients detect and render it automatically.

Clients that support MCP Apps interactive chart rendering (verified 2026-05-28):

| Client | MCP Apps | Notes |
| - | :-: | - |
| Cursor 2.6+ | ✅ | Desktop IDE; renders interactive Plotly iframe inline |
| VS Code Copilot Chat v1.109+ | ✅ | Browser-rendered panel with modebar |
| Goose | ✅ | Desktop app; renders iframes inline |
| Postman | ✅ | Renders in Postman canvas; good for dev/testing |
| MCPJam | ✅ | Inspector UI; best for debugging chart output |
| Claude Code (CLI) | ❌ | Terminal — no browser context; receives raw `plotly_json` |

> [!NOTE]
>
> Claude Code and other non-Apps clients receive the raw `plotly_json` response. Render it locally with `plotly.io.show(fig)` in Python or `Plotly.newPlot(...)` in JavaScript. To disable the embedded resource globally, set `MCP_APPS_ENABLED=false` on the Talk2Data service.

## Developer tools

Use these tools to test and debug CRAFT's MCP server during development, especially the MCP Apps / Plotly rendering path.

> [accordion] MCPJam Inspector
>
> [MCPJam](https://app.mcpjam.com) is a dedicated MCP inspector — web app (no install), desktop app, or CLI. It supports the MCP Apps extension and renders interactive Plotly charts inline.
>
> **Web app or desktop**: Add a server with URL `https://craft.emergence.ai/mcp`, enable OAuth, and set `X-Project-ID` in the headers field:
>
> ```json theme={null}
> {
>   "name": "craft",
>   "type": "http",
>   "url": "https://craft.emergence.ai/mcp",
>   "headers": { "X-Project-ID": "<your-project-id>" },
>   "useOAuth": true
> }
> ```
>
> **CLI**: Run a health check and OAuth flow validation:
>
> ```bash theme={null}
> npx @mcpjam/cli server doctor \
>   --url https://craft.emergence.ai/mcp \
>   --header "X-Project-ID: <your-project-id>"
> ```
>
> MCPJam provides full JSON-RPC trace visibility and guided OAuth conformance checks (DCR, PKCE, CIMD) — useful for validating the MCP server before shipping tool changes.

> [accordion] Postman
>
> Postman can act as an MCP host (client), connecting to external MCP servers — distinct from Postman's own MCP server for managing Postman resources.
>
> Go to **Settings → MCP Hosts → Add** and configure:
>
> * **URL**: `https://craft.emergence.ai/mcp`
> * **Auth**: OAuth (recommended) or access token
> * **Headers**: `X-Project-ID: <your-project-id>`
>
> Postman supports the MCP Apps extension — Plotly charts appear inline in the Postman canvas. Once you have a working configuration, use Postman's **Export MCP config** button to generate a ready-to-paste config for Claude Code, Cursor, or VS Code.

## Calling CRAFT from an external agent

Any MCP-compatible agent framework can use CRAFT as a tool server, bringing governed data access to any reasoning pipeline.

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart LR
    EA["External agent\n(any framework)"]
    GW["gateway-external\n(public HTTPS)"]
    MCP["em-runtime-mcp\n(tool gateway)"]
    ALLOW["Allowlist check\n+ audit event"]
    CATALOG["Catalog tools\nlist · get · search"]
    T2D["Talk2Data tools\nSQL · query · chart"]

    EA -->|"Streamable HTTP\nOAuth + X-Project-ID"| GW
    GW --> MCP
    MCP --> ALLOW
    ALLOW --> CATALOG
    ALLOW --> T2D

    classDef entry fill:#56B4E9,stroke:#555555,color:#000
    classDef infra fill:#0072B2,stroke:#555555,color:#fff
    classDef decision fill:#F0E442,stroke:#555555,color:#000
    classDef action fill:#E69F00,stroke:#555555,color:#000
    class EA entry
    class GW,MCP infra
    class ALLOW decision
    class CATALOG,T2D action
```

> [tab] Pydantic AI
>
> Requires `pydantic-ai-slim[fastmcp]` and `fastmcp`:
>
> ```python theme={null}
> from fastmcp import Client
> from fastmcp.client.transports import StreamableHttpTransport
> from pydantic_ai import Agent
> from pydantic_ai.toolsets.fastmcp import FastMCPToolset
>
> transport = StreamableHttpTransport(
>     url="https://craft.emergence.ai/mcp",
>     headers={
>         "Authorization": "Bearer <token>",
>         "X-Project-ID": "<your-project-id>",
>     },
> )
> toolset = FastMCPToolset(Client(transport))
> agent = Agent("anthropic:claude-opus-4-8", toolsets=[toolset])
>
> async def main():
>     result = await agent.run(
>         "What databases are available? Generate SQL to count active customers."
>     )
>     print(result.output)
> ```
>
> > [!NOTE]
> >
> > `MCPServerHTTP` is deprecated — use `FastMCPToolset` with `StreamableHttpTransport`.

> [tab] Google ADK
>
> Requires `google-adk`:
>
> ```python theme={null}
> from google.adk.agents import LlmAgent
> from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams
>
> agent = LlmAgent(
>     model="gemini-3.5-flash",
>     tools=[
>         MCPToolset(
>             connection_params=StreamableHTTPConnectionParams(
>                 url="https://craft.emergence.ai/mcp",
>                 headers={
>                     "Authorization": "Bearer <token>",
>                     "X-Project-ID": "<your-project-id>",
>                 },
>             )
>         )
>     ],
> )
> ```
>
> > [!NOTE]
> >
> > `SseServerParams` is the legacy SSE transport. Use `StreamableHTTPConnectionParams` for the MCP 2025-11-25 streamable-HTTP transport.

> [tab] Raw HTTP
>
> Any HTTP client can speak the MCP JSON-RPC protocol. List available tools:
>
> ```bash theme={null}
> # 1. Initialize a session
> curl -s -X POST https://craft.emergence.ai/mcp \
>   -H "Content-Type: application/json" \
>   -H "Accept: application/json, text/event-stream" \
>   -H "Authorization: Bearer <token>" \
>   -H "X-Project-ID: <your-project-id>" \
>   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}' \
> | jq .
> ```
>
> ```bash theme={null}
> # 2. List tools (include MCP-Session-Id from initialize response)
> curl -s -X POST https://craft.emergence.ai/mcp \
>   -H "Content-Type: application/json" \
>   -H "Authorization: Bearer <token>" \
>   -H "X-Project-ID: <your-project-id>" \
>   -H "MCP-Session-Id: <session-id>" \
>   -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
> | jq '.result.tools[].name'
> ```
>
> ```bash theme={null}
> # 3. Call a tool
> curl -s -X POST https://craft.emergence.ai/mcp \
>   -H "Content-Type: application/json" \
>   -H "Authorization: Bearer <token>" \
>   -H "X-Project-ID: <your-project-id>" \
>   -H "MCP-Session-Id: <session-id>" \
>   -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_schema","arguments":{"query":"customer"}}}' \
> | jq .
> ```
>
> Include `MCP-Session-Id` on all requests after initialization for stateful sessions.

> [!NOTE]
>
> Headless callers need a programmatic access token. Obtain one via a Keycloak service account (client credentials grant). See [Service Accounts](https://docs.emergence.ai/platform/service-accounts.md) for setup.

## Available tools

### Catalog tools

Always available — provide governed access to your project's data catalog.

| Tool | Required parameters | Returns |
| - | - | - |
| `hello_world` | — | Server greeting; confirms connectivity (no auth required) |
| `list_databases` | `resource_uri` — data connection UUID | Database metadata list |
| `get_schema` | `resource_uri`, `fqn` — 2 segments = database, 3 = schema, 4 = table | Full entity schema including columns and types |
| `search_schema` | `query` — Elasticsearch-style text query | Matching metadata entries across the project |

### Talk2Data tools

Available when the deployment includes the Data Insights solution. See [Data Connections](https://docs.emergence.ai/platform/data-connections.md) to connect your data sources.

| Tool | Required parameters | Returns |
| - | - | - |
| `generate_sql` | `question` (natural language), `database` (connection UUID), `schema` (object with `schema_name`) | `sql`, `explanation`, `assumptions` |
| `execute_query` | `sql` (SELECT statements only), `database` | `columns`, `rows`, `row_count`, `truncated` |
| `resolve_term` | `term` — business term (e.g., "ARR", "churn rate") | `definition`, `related_columns`, `sql_pattern` |
| `generate_plotly_chart` | `data` (tabular), `chart_type` (bar, line, scatter, pie, …) | Plotly JSON figure spec (`plotly_json`) + interactive iframe for MCP Apps clients |
| `sample_data` | `resource_uri`, `table_fqn` — `database.schema.table` | `columns`, `rows` (up to 100 rows preview) |

> [!NOTE]
>
> `execute_query` only accepts SELECT statements — DDL, DML, and admin functions are rejected. `generate_sql` delegates to the Text2SQL A2A agent; the first call in a session may take 3–8 s (cold start), subsequent calls \~1–2 s. `generate_plotly_chart` emits per-stage MCP progress notifications (parse → validate → render → verify) forwarded as A2A status events — visible in clients that display progress.

## Per-project allowlist and governance

CRAFT enforces a per-project tool allowlist — each project defines which tools each agent identity may call. This is the key difference between the CRAFT MCP gateway and a raw FastMCP server.

Configure allowlists in [Platform → Authorization](https://docs.emergence.ai/platform/authorization.md) (RBAC model) and [Platform → Agents](https://docs.emergence.ai/platform/agents.md) (agent identity → allowlist mapping). Denied calls return a structured error:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "tool_not_allowed",
    "message": "Tool 'generate_sql' is not in the allowlist for this agent identity"
  }
}
```

Every tool call — allowed or denied — writes an audit event to the governance event log. Each event records:

* Timestamp, agent identity, tool name, project ID
* Input parameters (PII-scrubbed per governance policy)
* Result status (allowed / denied / error)

Query audit events via [Audit Log](https://docs.emergence.ai/guides/customer-admin/audit-log.md). Tool calls are tracked separately from LLM completions and do not flow through the LiteLLM gateway. See [LLM Gateway](https://docs.emergence.ai/platform/llm-gateway.md) for the complementary table.

## Errors and limits

| Condition | HTTP | MCP error code | Remediation |
| - | - | - | - |
| Missing `Authorization` header | 401 | `missing_authorization` | Complete the OAuth flow; verify token is fresh |
| Missing `X-Project-ID` header | 400 | `missing_project` | Add `X-Project-ID` header with your project UUID |
| Tool not in allowlist | 403 | `tool_not_allowed` | Ask project admin to add tool to allowlist |
| Non-SELECT SQL in `execute_query` | 422 | `validation_error` | Only SELECT statements are permitted |
| Text2SQL agent unavailable | 503 | `upstream_unavailable` | Retry; `generate_sql` depends on the Talk2Data A2A agent |
| Query row limit hit | 200 | — | Response includes `"truncated": true`; add a `LIMIT` or more selective `WHERE` clause to fit within 500 rows |

**Limits:**

* `execute_query`: server-enforced cap of 500 rows; `truncated: true` in response when exceeded
* `sample_data`: up to 100 rows (`limit` parameter; default 10)
* `generate_sql`: first call may take 3–8 s (Text2SQL agent cold-start); subsequent calls \~1–2 s

## Next steps

> [card] [LLM Gateway](https://docs.emergence.ai/platform/llm-gateway.md)
>
> The complementary gateway for LLM completions — model allowlist, rate limits, and cost attribution.

> [card] [Data Connections](https://docs.emergence.ai/platform/data-connections.md)
>
> Connect your data sources to enable Talk2Data tools.

> [card] [Release Notes](https://docs.emergence.ai/releases.md)
>
> Track new tools, breaking changes, and platform updates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.