Model Context Protocol (MCP) Server

Synaplan ships a built-in MCP server so AI clients — Claude, Cursor, VS Code, and any other Model Context Protocol host — can use your Synaplan workspace as a set of tools, with one connection and one API key.

Status: Early access. The first release exposes read-only knowledge tools (rag_search, memory_search). More tools (chat, memory writes, file ingestion, prompts, resources) are on the roadmap, and the protocol surface may still change.

Why MCP (beyond the REST API)

The REST API and OpenAI-compatible endpoints are ideal when you write the integration. MCP is different: the client discovers what Synaplan can do and calls it automatically — no per-client glue code. Point a compatible host at one URL and your Synaplan knowledge base and memories become tools the model can use on its own.

Endpoint

Authentication

Authenticate every request with a Synaplan API key (create one in Settings → API Keys). Either header works:

• X-API-Key: YOUR_SYNAPLAN_API_KEY
• Authorization: Bearer YOUR_SYNAPLAN_API_KEY

Enterprise SSO deployments may also send an OIDC bearer token (Keycloak). Unauthenticated requests receive a 401 with a WWW-Authenticate header pointing at the RFC 9728 Protected Resource Metadata document, so OAuth-capable clients can discover the authorization server automatically.

Every call is scoped to the account that owns the key — tools only ever see that user's documents and memories.

Connect a client

Most MCP hosts let you add a remote (HTTP) server with custom headers. The configuration usually looks like this:

{
  "mcpServers": {
    "synaplan": {
      "url": "https://web.synaplan.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_SYNAPLAN_API_KEY"
      }
    }
  }
}

The exact file and location depend on the client (Claude Desktop, Cursor, VS Code, …) — use your host's "add remote MCP server" flow and supply the URL and header above.

Available tools

Each tool returns both human-readable text and structured JSON.

Try it with cURL

MCP uses JSON-RPC 2.0 over a single endpoint. The flow is initialize → tools/list → tools/call.

1. Initialize — returns an Mcp-Session-Id response header to reuse:

curl -i -X POST https://web.synaplan.com/mcp \
     -H "X-API-Key: YOUR_SYNAPLAN_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

2. List tools — replace SESSION with the Mcp-Session-Id from step 1:

curl -X POST https://web.synaplan.com/mcp \
     -H "X-API-Key: YOUR_SYNAPLAN_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "MCP-Protocol-Version: 2025-11-25" \
     -H "Mcp-Session-Id: SESSION" \
     -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

3. Call a tool:

curl -X POST https://web.synaplan.com/mcp \
     -H "X-API-Key: YOUR_SYNAPLAN_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "MCP-Protocol-Version: 2025-11-25" \
     -H "Mcp-Session-Id: SESSION" \
     -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"rag_search","arguments":{"query":"quarterly report","limit":5}}}'

Roadmap

Planned additions, in priority order:

• synaplan_chat — full chat through Synaplan's routing pipeline (classification → web search → RAG → inference), not just a raw model call.
• Write tools: memory_add, file_ingest.
• More read tools: rag_similar, list_chats / get_messages, list_prompts.
• Resources (documents, memories, shared chats as addressable URIs) and Prompts (your task prompts as host-selectable templates).
• A listing in the public MCP registry for one-click install.

See also

• REST API Structure
• Interactive API (Swagger)
• Code Examples
• Model Context Protocol specification