MCP integration

Gyrence exposes all five primitives over the Model Context Protocol (MCP) at a single hosted endpoint. If your agent runtime speaks MCP — Claude Desktop, Cursor, Continue, an OpenAI Responses-API client, your own SDK — you can drop Gyrence in without writing HTTP plumbing.

Everything you read here is additive to the HTTP API. Same workspace, same API key, same credits, same activity log. Picking MCP vs. HTTP is a transport choice, not an account choice.

What is MCP?

The Model Context Protocol is an open spec for connecting LLM-driven agents to external tools and data sources. An MCP server advertises a set of tools (typed JSON-RPC methods); a client (your agent runtime) calls them on the agent's behalf.

Gyrence's MCP server advertises five tools — one per primitive — and the client picks which to call based on the agent's reasoning. The wire protocol is JSON-RPC 2.0, transported over HTTP with optional Server-Sent Events for streaming responses.

You do not need to know any of this to use Gyrence via MCP. You configure your client once with the endpoint and an API key; the rest is the agent doing what agents do.

The endpoint

POST https://www.gyrence.com/api/mcp
Authorization: Bearer mc_<your-key>
Content-Type: application/json

That's the entire surface — one URL, one bearer token, JSON-RPC bodies in and JSON or SSE out. There are no per-tool subpaths, no session cookies, no separate handshake.

GET and DELETE are rejected with HTTP 405. The MCP standalone-SSE channel is not offered today.

The tools

The MCP server exposes exactly the five primitives, named with the gyrence_ prefix so they don't collide with other servers your client might be wired to:

Tool descriptions (visible to the model during selection) call out credit cost and link back to the live credit schedule at /docs/concepts/credits. The schemas advertised over MCP are the same Zod objects that validate the HTTP requests — searchHandler.schema, fetchHandler.schema, and so on. There is no possibility of drift between the two transports.

Billing parity

This is the central guarantee, and it's worth stating plainly: a call via MCP costs exactly the same as the equivalent HTTP call, and produces an identical row in your usage_events.

This isn't a careful audit — it's how the code is structured. Each MCP tool's execute synthesizes an internal Request and calls the same handle() function the HTTP route delegates to. That function is the only place credit metering, status mapping, and the recordUsage write happen. There is no separate MCP code path that could diverge.

Concretely, after an MCP tools/call for gyrence_gyre, you'll see a usage_events row with:

• endpoint = "gyre" (the primitive, not "mcp")
• credits_used, via, status_code, status, latency_ms — all identical in shape to an HTTP call
• url — the seed URL passed in the tool arguments

The Activity page in the console shows MCP and HTTP traffic in the same table. There is no MCP vs. HTTP filter because, at the billing/audit layer, there's nothing to filter — it's the same event.

Authentication and concurrency

Two implementation choices worth knowing about:

• Header auth, parsed up-front. Every request starts with parseBearer(request) + authenticateMcpKey(key). A missing or invalid key returns JSON-RPC error -32001 ("Unauthorized") with HTTP 401. Failed auth is never billed.
• Per-request MCP server. Gyrence constructs a fresh McpServer instance per request, with the parsed key captured in each tool's closure. Two concurrent calls authenticated with different keys cannot share server state. This was verified end-to-end: six interleaved requests across two workspaces produced zero cross-attribution.

In practice this means MCP behaves exactly like HTTP for concurrency: per-workspace rate limits and the 25-second hard deadline apply identically.

Configuring a client

The exact configuration shape varies by client, but the inputs are always the same: the URL and the bearer token.

Claude Desktop

Add an entry to claude_desktop_config.json under mcpServers:

{
  "mcpServers": {
    "gyrence": {
      "transport": {
        "type": "http",
        "url": "https://www.gyrence.com/api/mcp",
        "headers": {
          "Authorization": "Bearer mc_your_key_here"
        }
      }
    }
  }
}

Restart Claude Desktop. The five gyrence_* tools appear in the tool picker; Claude will reach for them when a prompt implies web data work.

Cursor

Cursor's MCP config (~/.cursor/mcp.json or the in-app settings) takes the same shape:

{
  "mcpServers": {
    "gyrence": {
      "url": "https://www.gyrence.com/api/mcp",
      "headers": {
        "Authorization": "Bearer mc_your_key_here"
      }
    }
  }
}

Anything else

If your client speaks MCP over HTTP, you need exactly:

• URL: https://www.gyrence.com/api/mcp
• Method: POST
• Headers: Authorization: Bearer mc_…, Content-Type: application/json

The body is whatever JSON-RPC payload your client emits. The server speaks the standard MCP methods (initialize, tools/list, tools/call, notifications/initialized).

For a minimal raw-curl tools/call example, see API → MCP.

When to pick MCP vs. HTTP

Use MCP when:

• The consuming surface is an agent runtime (Claude Desktop, Cursor, an MCP-aware framework). The integration is one config block instead of a custom tool wrapper per primitive.
• You want the agent to pick which primitive to call. The tool descriptions are written to guide selection: gyrence_search when there's no URL, gyrence_fetch for one known URL, etc.
• You want zero code on your side to map primitives to tools.

Use HTTP when:

• You're building a non-agent pipeline (a batch job, a webhook handler, a cron). Plain HTTP is simpler than wiring an MCP client.
• You need to drive the call deterministically from your own code (e.g. "always fetch this URL when X happens"). MCP adds a layer of model-driven dispatch you don't want.
• You're shipping an SDK — the HTTP API is the stable surface SDKs are generated from (/openapi.json).

Most teams end up using both: HTTP for the deterministic backend pipelines, MCP for the agent surfaces.

What MCP does not add

A short list of "it's HTTP under the hood, so this is the same":

• No separate plan, no separate pricing. MCP traffic counts against the same monthly credit pool as HTTP.
• No separate rate limits. Per-workspace limits and the 25-second deadline are shared across transports.
• No richer auth model. A key that works over HTTP works over MCP, and vice versa. Per-key scopes are not shipped today.
• No new primitives. If a primitive isn't on the HTTP API, it isn't on MCP either. The two are mirror images.