Connecting Clients

MCP endpoints are in beta.

To connect, an MCP client needs three things from you: the endpoint URL, a way to get a token for its principal, and its grant id. See Authentication and grants for how you issue them. The endpoint URL ends with the current publication revision. Read it after each push:

bijection run mcp:revision

The URL is then https://<your deployment name>.bijection.site/mcp/<revision>. When you push a change, give clients the new URL.

Trying the endpoint

The endpoint is a stateless JSON-RPC endpoint over HTTP POST. You can list its tools with curl:

curl "https://happy-animal-123.bijection.site/mcp/$REVISION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Method: tools/list" \
  -H "Mcp-Protocol-Version: 2026-07-28" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "curl", "version": "1" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

The response lists only the tools in your grant.

Read-only clients

Any MCP client that can send a bearer token to a remote HTTP server can discover tools and call query and status tools. Give it the endpoint URL and a token. Operation tools are different. Each operation call needs a request key that stays the same across retries, and a model can’t be trusted to invent one. A client that doesn’t supply the key and grant id can’t call operation tools; those calls fail with request_scope_mismatch.

Recoverable writes

The bijection/mcp/node module gives an agent host what it needs to call operation tools safely. It runs in your agent’s Node.js process, not in your deployment. Don’t import it from your bijection/ folder.

agent/connection.ts

import { connectMcp, McpRequestJournal } from "bijection/mcp/node";

const connection = connectMcp({
  publicationUrl: "https://happy-animal-123.bijection.site/mcp/3f9c…e81a",
  deploymentUrl: "https://happy-animal-123.bijection.cloud",
  grantId: process.env.MCP_GRANT_ID!,
  getToken: async () => await fetchTokenFromYourIdentityProvider(),
  store: new McpRequestJournal("/var/lib/agent/mcp-journal"),
});

publicationUrl is the endpoint URL. It must end with the revision and use HTTPS, or HTTP on a loopback address.
deploymentUrl is your deployment’s .bijection.cloud URL. It is used for recovery and status, which call your operation’s recovery functions directly and keep working after the endpoint URL changes.
getToken is called for every HTTP request, so tokens can be refreshed freely. Tokens are never written to the store.
store persists each write’s request before it is sent.

The connection has these methods:

Method	What it does
`discover()`	Lists the granted tools and records each operation tool’s recovery binding.
`fetchForCall(id)`	Returns a `fetch` for one tool call. Operation calls get a request key from the store, keyed by `id`, outside the model’s arguments.
`recover(id)`	Returns the original result of the write recorded for `id`, under the caller’s current permissions. It never resubmits.
`status(id)`	Returns the execution status of the write recorded for `id` without releasing its business result.

The call id must stay the same when your host replays a step, for example a persisted workflow step identity. Calling an operation tool again with the same id returns the same invocation.

A timeout, dropped connection or 5xx response doesn’t tell you whether a write was accepted. Call recover(id) or status(id) with the original call id. Never retry with a new id: that is a new request.

Request stores

McpRequestJournal is a small file-based store that syncs each record to disk before the request is sent. Put its directory on durable storage. For production hosts, implement the McpRequestStore interface on your own database:

interface McpRequestStore {
  prepare(
    callId: string,
    input: Omit<McpRequestRecord, "request_key">,
  ): Promise<McpRequestRecord>;
  load(callId: string): Promise<McpRequestRecord | null>;
}

prepare must atomically keep one immutable record per call ID, return the same request key when called again with the same input, and reject a call ID reused with different arguments, grant or endpoint. load must survive a process restart. Never store credentials in it.

Mastra

Pass the connection’s fetch to Mastra’s MCP client. Create one client per tool call ID:

agent/mastra.ts

import { MCPClient } from "@mastra/mcp";

const client = new MCPClient({
  id: callId,
  timeout: 10_000,
  servers: {
    tasks: {
      url: new URL(publicationUrl),
      fetch: connection.fetchForCall(callId),
    },
  },
});
const tools = await client.listTools(); // e.g. tasks_list_tasks, tasks_complete_task

Eve

Eve persists its own session and call identity. Use eveMcpRequest as a provided argument; Eve hides it from the model and adds it to each call:

agent/connections/tasks.ts

import { defineMcpClientConnection } from "eve/connections";
import { eveMcpRequest } from "bijection/mcp/node";

export default defineMcpClientConnection({
  url: publicationUrl,
  description: "Task lookups and completions.",
  instanceKey: `${grantId}:${publicationUrl}`,
  auth: { getToken: async () => ({ token: await getToken() }) },
  tools: { allow: ["list_tasks", "complete_task", "task_status"] },
  toolCall: {
    providedArguments: { __bijection_request: eveMcpRequest(grantId) },
  },
});

Keep each connection bound to one grant and one endpoint URL.

Other clients

If you build your own client, send the request identity in the tool call’s _meta, never in the model’s arguments:

{
  "jsonrpc": "2.0",
  "id": "call-1",
  "method": "tools/call",
  "params": {
    "name": "complete_task",
    "arguments": { "task": "…" },
    "_meta": {
      "bijection/request": {
        "request_key": "<stable key, 1–256 characters>",
        "grant_id": "<grant id>"
      }
    }
  }
}

Add "mode": "recover" to look up an earlier call with the same key and arguments without invoking the operation. Persist the key before sending the request.

Errors and deadlines

Each discovery, recover and status attempt, including getting a token, has a 10-second deadline. Set your MCP client’s own timeout for tool calls, as in the Mastra example above. Failures are thrown as McpRequestError with a kind of deadline, cancelled, unavailable, authorization or request_refused. None of them establishes whether a write committed.

Presenting status

presentMcpOutcome from bijection/mcp/outcome turns a status tool’s result into a fixed outcome and message for your users, such as pending, awaiting_review or unknown. Its external_effect_confirmed field is always false: delivery records alone don’t prove that an external system applied a change. Show these facts directly rather than a model’s summary of them.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Connecting Clients

Trying the endpoint

Read-only clients

Recoverable writes

Request stores

Mastra

Eve

Other clients

Errors and deadlines

Presenting status

​Trying the endpoint

​Read-only clients

​Recoverable writes

​Request stores

​Mastra

​Eve

​Other clients

​Errors and deadlines

​Presenting status

Trying the endpoint

Read-only clients

Recoverable writes

Request stores

Mastra

Eve

Other clients

Errors and deadlines

Presenting status