Configure MCP

Overview

Monospace exposes a Model Context Protocol (MCP) server so AI agents and tools can read and write your data through the same governed API as the rest of your stack. Every tool call runs under the permissions of the API key you connect with — agents can only do what that key is allowed to do.

The MCP server is per workspace. Each workspace has its own endpoint:

https://{your-instance}/api/{workspace}/mcp

Prerequisites

Before connecting a client, you need:

• An API key — create one in the Studio under Account Settings > Access. The key inherits the permissions of whoever it belongs to — a regular user or a service account — so the agent can only access what they can. See Authentication for details.
• The ai:mcp entitlement — granted through the role attached to the key's owner. If tools never appear in your client, this is the first thing to check.
• Your instance host and workspace name — these fill the {your-instance} and {workspace} placeholders in the endpoint URL.

Connect Your Client

Every client needs the same three facts: the remote HTTP transport, the per-workspace URL, and the Authorization: Bearer header. Replace the {your-instance} and {workspace} placeholders below with your instance host and workspace name. The server label (monospace in the examples) is an arbitrary name you choose to identify the connection in your client.

Claude Code

Add the server with the claude mcp command:

claude mcp add --transport http monospace https://{your-instance}/api/{workspace}/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Or configure it directly in a project-level .mcp.json:

{
  "mcpServers": {
    "monospace": {
      "type": "http",
      "url": "https://{your-instance}/api/{workspace}/mcp",
      "headers": {
        "Authorization": "Bearer ${MONOSPACE_API_KEY}"
      }
    }
  }
}

Claude Code expands ${MONOSPACE_API_KEY} from your environment, keeping the key out of the file.

Claude Desktop

Claude Desktop's Add custom connector dialog only supports OAuth, so a static API key cannot be entered there yet. Connect it instead through mcp-remote, a local stdio-to-HTTP bridge, in claude_desktop_config.json:

{
  "mcpServers": {
    "monospace": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://{your-instance}/api/{workspace}/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Splitting the header as Authorization:${AUTH_HEADER} (no space) with the value in env avoids Claude Desktop mishandling the space in the argument. Restart Claude Desktop fully after editing — it reads the config only on launch.

Codex

Add the server with the codex mcp add command:

codex mcp add monospace --url https://{your-instance}/api/{workspace}/mcp \
  --bearer-token-env-var MONOSPACE_API_KEY

--bearer-token-env-var names the environment variable holding your key — Codex sends its value as the Authorization: Bearer token, keeping the key out of the command.

OpenAI

Attach the server as a remote MCP tool. With the Responses API, add an entry to the tools array and pass the key in headers:

{
  "type": "mcp",
  "server_label": "monospace",
  "server_url": "https://{your-instance}/api/{workspace}/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  },
  "require_approval": "never"
}

With the Agents SDK (Python), use MCPServerStreamableHttp:

from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    name="monospace",
    params={
        "url": "https://{your-instance}/api/{workspace}/mcp",
        "headers": {"Authorization": "Bearer YOUR_API_KEY"},
    },
) as server:
    ...

Gemini CLI

Add the server to .gemini/settings.json with url, and pass the key in headers:

{
  "mcpServers": {
    "monospace": {
      "url": "https://{your-instance}/api/{workspace}/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Add the server to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), with the url and a headers object:

{
  "mcpServers": {
    "monospace": {
      "url": "https://{your-instance}/api/{workspace}/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Connect a URL-Only Client

Some MCP clients accept only a connection URL and cannot attach an Authorization header. Append the API key as the access_token query parameter — the MCP server accepts it exactly like the header.

https://{your-instance}/api/{workspace}/mcp?access_token=YOUR_API_KEY

Provide the token through one source only. Sending both an Authorization header and an access_token query parameter fails with 400 Bad Request.

Available Tools

The server exposes seven tools. Each call is checked against the connecting key's permissions.

For how permissions are configured, see Access & Permissions. For the underlying data operations, see Reading Data and Writing Data.

Verify the Connection

Send an unauthenticated POST to the endpoint to confirm it is reachable:

curl -s -o /dev/null -w "%{http_code}" \
  -X POST https://{your-instance}/api/{workspace}/mcp

A 403 confirms the server is up and the path is correct — the request is rejected because it is unauthenticated. A 404 means the path is wrong; a connection refused or timeout means the host or port is wrong.

Once configured in your client with an entitled key, the seven tools above should appear in its tool list.

Troubleshooting

• No tools appear — confirm the credential is present (the Authorization: Bearer header or the access_token query parameter) and the key is valid, and that the key's owner has the ai:mcp entitlement. Missing tools almost always means auth or entitlement, not transport.
• Wrong URL — the path must be /api/{workspace}/mcp with the correct workspace name. There is no /api/mcp or system-wide MCP endpoint.
• A tool returns forbidden — the key lacks the permission for that tool (for example, read_schema requires dataModel:read). Create a key whose owner has the needed permissions.
• 405 Method Not Allowed — the MCP server accepts POST only. Ensure your client uses the streamable-HTTP transport, not SSE.

Next Steps

• Authentication — create and manage API keys
• Access & Permissions — scope what an agent can do
• REST API Quickstart — the same data, over HTTP