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; 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:

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:

{"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:

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. 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 and Authentication.

Connect your AI client

Claude Code

Add the CRAFT MCP server from the CLI:

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):

{
  "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.

Find your project ID in the CRAFT console under Settings → Project → ID.

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "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.

VS Code

Create .vscode/mcp.json in your project:

{
  "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.

If tool calls fail silently, headers may not be forwarded — a known issue in some VS Code versions (#264095). Workaround: replace the type/url block with mcp-remote:

{
  "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.

Goose

Add to ~/.config/goose/config.yaml:

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. 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`

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.

MCPJam Inspector

MCPJam 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:

{
  "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:

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.

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.

Pydantic AI
Google ADK
Raw HTTP

Requires pydantic-ai-slim[fastmcp] and fastmcp:

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)

MCPServerHTTP is deprecated — use FastMCPToolset with StreamableHttpTransport.

Requires google-adk:

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>",
                },
            )
        )
    ],
)

SseServerParams is the legacy SSE transport. Use StreamableHTTPConnectionParams for the MCP 2025-11-25 streamable-HTTP transport.

Any HTTP client can speak the MCP JSON-RPC protocol. List available tools:

# 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 .

# 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'

# 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.

Headless callers need a programmatic access token. Obtain one via a Keycloak service account (client credentials grant). See Service Accounts 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 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)

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 (RBAC model) and Platform → Agents (agent identity → allowlist mapping). Denied calls return a structured error:

{
  "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. Tool calls are tracked separately from LLM completions and do not flow through the LiteLLM gateway. See LLM Gateway 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

LLM Gateway

The complementary gateway for LLM completions — model allowlist, rate limits, and cost attribution.

Data Connections

Connect your data sources to enable Talk2Data tools.

Release Notes

Track new tools, breaking changes, and platform updates.

​MCP Server

​Server details

​Verify the endpoint (no auth needed)

​Authentication

​Interactive clients (OAuth)

​X-Project-ID header

​Token requirements for headless callers

​Connect your AI client

​Interactive charts — MCP Apps extension

​Developer tools

​Calling CRAFT from an external agent

​Available tools

​Catalog tools

​Talk2Data tools

​Per-project allowlist and governance

​Errors and limits

​Next steps

LLM Gateway

Data Connections

Release Notes

MCP Server

Server details

Verify the endpoint (no auth needed)

Authentication

Interactive clients (OAuth)

X-Project-ID header

Token requirements for headless callers

Connect your AI client

Interactive charts — MCP Apps extension

Developer tools

Calling CRAFT from an external agent

Available tools

Catalog tools

Talk2Data tools

Per-project allowlist and governance

Errors and limits

Next steps