Skip to content
    Marres Insights
    Documentation contents

    DOCS / MCP SERVER

    MCP server

    Connect Claude, ChatGPT developer mode and other AI assistants to Marres through the remote MCP endpoint.

    Marres exposes a remote MCP (Model Context Protocol) server so AI assistants — Claude, ChatGPT, and any other MCP-capable client — can read analyses and launch work through one standard interface.

    https://marresinsights.com/mcp

    It is a thin layer over the same capabilities as the Agent API: the same scopes, the same rate limits, the same run lifecycle. If you are writing your own integration code, prefer the REST API; if you are connecting an AI assistant, use MCP.

    Authentication

    The MCP server accepts two kinds of bearer tokens:

    Token kindFormatHow to get one
    OAuth 2.1Any bearer stringChatGPT / MCP-client OAuth flow (sign in with your Marres account — no key handling needed)
    Agent API keymk_...Settings → Agent API keys (for Claude, scripts, or developer mode)

    Both token kinds enforce the same scope and rate-limit rules per tool call.

    OAuth connection (ChatGPT and OAuth-capable MCP clients)

    ChatGPT's polished connector flow uses OAuth 2.1 — you sign in with your Marres account and no API key is ever copied:

    1. In ChatGPT, open Settings → Connectors → Add connector.
    2. Enter the MCP server URL: https://marresinsights.com/mcp.
    3. ChatGPT discovers the OAuth server automatically via /.well-known/oauth-protected-resource.
    4. You are redirected to the Marres sign-in page, where you log in and approve the connection.
    5. ChatGPT stores the token — you will not see it.
    6. Enable the connector in a conversation and ask ChatGPT to "list my Marres analyses" to verify.

    The OAuth discovery endpoints are:

    • /.well-known/oauth-protected-resource — protected resource metadata (RFC 9728)
    • /.well-known/oauth-authorization-server — authorization server metadata (RFC 8414)
    • POST /oauth/register — dynamic client registration (RFC 7591)

    OAuth access tokens expire after 1 hour. ChatGPT handles re-authorisation automatically when a token expires.

    Agent API key (Claude, scripted access, ChatGPT developer mode)

    1. Create a key in the platform (Settings → Agent API keys). The full secret (mk_...) is shown once; treat it like a password.
    2. The client must send it on every request as Authorization: Bearer mk_your_key_here.
    3. Scopes are enforced per tool call: read:analyses for analysis tools, read:runs for run tools, agent:run for execute_preview / execute_confirm. A key missing a scope gets a clear tool error, not a silent failure.
    4. Rate limits are shared with the REST API: per key and per scope over a 60-second window (60/window for reads, 10/window for agent:run).

    Key-authenticated calls never carry administrator powers, and ownership rules are identical to the REST API: a resource that is missing and a resource that belongs to someone else produce the same "not found" answer.

    Connecting from Claude

    Claude supports remote MCP servers as custom connectors:

    1. In Claude, open Settings → Connectors → Add custom connector.
    2. Name: Marres. URL: https://marresinsights.com/mcp.
    3. Under advanced/authentication, choose Bearer token (or paste the header value if prompted) and supply your mk_... key.
    4. Save, then enable the connector in a conversation. Ask Claude to "list my Marres analyses" to verify.

    Connecting from ChatGPT (developer mode)

    1. Enable developer mode (Settings → Connectors → Advanced → Developer mode).
    2. Add a new connector with the URL https://marresinsights.com/mcp and authentication type "Access token / API key", pasting your mk_... key.
    3. Use it from a chat with the connector enabled.

    Tools

    Tools map 1:1 onto the REST endpoints:

    ToolScopeMirrors
    list_analysesread:analysesGET /api/v1/analyses
    get_analysisread:analysesGET /api/v1/analyses/{id}
    get_analysis_contextread:analysesGET /api/v1/analyses/{id}/context
    get_analysis_capabilitiesread:analysesGET /api/v1/analyses/{id}/capabilities
    get_analysis_artefactsread:analysesGET /api/v1/analyses/{id}/artefacts
    get_analysis_historyread:analysesGET /api/v1/analyses/{id}/history
    list_runsread:runsGET /api/v1/runs?module=...
    get_runread:runsGET /api/v1/runs/{id}
    get_run_outputread:runsGET /api/v1/runs/{id}/output
    execute_previewagent:runPOST /api/v1/execute/preview
    execute_confirmagent:runPOST /api/v1/execute/confirm

    Run lifecycle

    Launching work follows the same preview → confirm → poll pattern as the REST API:

    1. execute_preview queues a pending run — free, nothing charged. A new preview replaces any previously queued one and expires after 10 minutes.
    2. execute_confirm charges credits and launches the queued preview, returning run ids. Confirming with nothing queued (or an expired preview) fails with a CONFLICT error, so a duplicate confirm cannot double-charge.
    3. Poll get_run with each id no more than once every 10 seconds until a terminal status: succeeded, failed or cancelled.
    4. On succeeded, get_run_output returns the outputs and derived artefacts.

    Transport notes

    • The endpoint speaks Streamable HTTP (the current MCP remote transport) and is stateless: no sessions, no SSE resume stream. POST /mcp only.
    • Errors inside tools are returned as tool errors with stable prefixes (NOT_FOUND, CONFLICT, INSUFFICIENT_CREDITS, VALIDATION_ERROR, UNPROCESSABLE, INTERNAL_ERROR), so assistants can react sensibly.
    • For scripted access, health checks, or anything that is not an AI assistant, use the Agent API instead.

    Related product page: Agent API — REST reference

    ← Agent APIGlossary →

    Documentation draft · Source baseline 16 August 2026