MCP Integration Overview

How Mandraki implements the Model Context Protocol (MCP), enabling AI assistants and developer tools to interact with your workspace programmatically.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants and developer tools interact with external services through a unified interface. Instead of learning a bespoke REST API, any MCP-compatible client (Claude Code, Cursor, Windsurf, and others) can discover available tools at runtime and call them using the same JSON-RPC 2.0 protocol.

Mandraki implements MCP natively. When you connect an AI assistant to your Mandraki workspace, it can create tasks, search messages, manage calendar events, upload files, and more — all through the same tools that power Mandraki’s built-in AI assistant.

Endpoints

Mandraki exposes two MCP transport endpoints:

Endpoint	Method	Description
`/api/v1/mcp`	`POST`	JSON-RPC 2.0 request/response. Send a single request, get a single response.
`/api/v1/mcp/sse`	`GET`	Server-Sent Events stream. Receives an initial `initialize` result on connection, then keepalive pings every 30 seconds.

The POST endpoint is what most MCP clients use. You send a JSON-RPC 2.0 request and receive a JSON-RPC 2.0 response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

The SSE endpoint is for clients that need a persistent connection. On connect, it sends the server’s initialize result (server info and capabilities) as the first event.

Authentication

All MCP requests require authentication via the Authorization header:

Authorization: Bearer mak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens are created in Settings > API within the Mandraki app. Each token is scoped to a service account and a specific set of permissions (scopes). See Connecting Claude Code for setup instructions.

Mandraki also accepts JWT session tokens (the same tokens used by the web app), but API tokens (mak_ prefix) are recommended for integrations because they are scoped, revocable, and do not expire with user sessions.

Capabilities

When a client sends an initialize request, Mandraki responds with its capabilities:

{
  "serverInfo": {
    "name": "mandraki",
    "version": "1.0.0",
    "protocolVersion": "2024-11-05"
  },
  "capabilities": {
    "tools": { "listChanged": false },
    "resources": { "subscribe": false, "listChanged": false }
  },
  "protocolVersion": "2024-11-05"
}

Tools

Mandraki exposes tools from its app framework. Each registered app (tasks, calendar, drive, chat, mail) contributes tools that the MCP server makes available. Tools are scope-filtered — a token with only tasks:read and tasks:write scopes will only see task-related tools.

Resources

Mandraki exposes app context providers as MCP resources. Each app can publish contextual data (summaries, recent items) at a URI like mandraki://app/tasks/context. Resources provide read-only context that AI assistants can use to understand the current workspace state.

How MCP Differs from the REST Bot API

Aspect	MCP	REST Bot API
Protocol	JSON-RPC 2.0 over HTTP	REST (GET/POST/PUT/DELETE)
Tool discovery	Dynamic via `tools/list`	Fixed endpoint documentation
Intended client	AI assistants, code editors	Custom bots, webhooks, scripts
Auth	Same `mak_` tokens	Same `mak_` tokens
Scope filtering	Automatic — client only sees permitted tools	Manual — developer checks docs
Execution	Through ToolBroker (policy + audit)	Direct route handlers

Use MCP when connecting AI-powered tools that support the protocol. Use the REST Bot API when building custom integrations, webhooks, or scripts where you control the HTTP calls directly.

Supported MCP Methods

Method	Description
`initialize`	Returns server info and capabilities
`ping`	Health check, returns empty object
`tools/list`	List available tools (filtered by token scopes)
`tools/call`	Execute a tool by name with arguments
`resources/list`	List available context resources