MCP Gateway API

The Fabric MCP Gateway exposes a single endpoint that implements the MCP 2025-03-26 Streamable HTTP transport. It works with any MCP-compatible client.

Endpoint

POST https://your-fabric.com/api/mcp-gateway/projects/<project-id>

A project has its own gateway URL, and a connection made at it reaches that project and nothing else: the tools are the project's own (the instruction, feature, document, context and knowledge tools, with projectId optional and defaulting to the project), and no organization-wide tool or connected server is offered or callable. The organization-wide endpoint, POST https://your-fabric.com/api/mcp-gateway, serves the connections made before projects had their own URL.

Authentication

Include one of the following:

A signed-in agent's token is issued for one resource and works only there. A token issued for a project works at that project's URL and nowhere else; an organization-wide token works at the organization-wide URL; a token issued for the REST API works at neither gateway URL. A client asks for the resource by sending it as the resource parameter of its authorization and token requests, and a project URL refuses a sign-in that does not name the project.

API keys and browser sessions are accepted at a project's URL after a live check that the key's owner can read the project, and the session is then bound to the project: an organization key must belong to the organization hosting it.

A new organization API key starts with mcp:read only. mcp:write satisfies every write tool, so a key that holds it can change workflows, pages and features; for an agent that should do one thing, give the key the narrow scope instead (workflows:write, frames:write, features:write, and so on). Keys created earlier keep the scopes they were given.

The Fabric Kanban API uses separate scopes rather than the MCP umbrella: kanban:read lists the caller's queue and identity, while kanban:write pulls and completes the caller's items. Neither scope implies the other. Under your organization's Settings → API keys, create a key and select Kanban Read and Kanban Write. A read-only organization role can select only Kanban Read, so its key cannot pull or complete items. Existing keys without these scopes need to be replaced from the same settings page before they can use these routes.

Without valid credentials the gateway answers 401 with WWW-Authenticate: Bearer resource_metadata="https://your-fabric.com/.well-known/oauth-protected-resource/api/mcp-gateway/projects/<project-id>", scope="mcp:read instructions:read instructions:write offline_access" (the organization-wide URL names .../oauth-protected-resource/api/mcp-gateway), which is how an MCP client discovers that it can sign in. A token that is genuine but was not issued for the URL it was presented at is answered 401 the same way, with error="invalid_token" added, which sends the client back through sign-in asking for the right resource. The project metadata's resource is exactly the project's URL. See Fabric MCP Gateway for the setup.

MCP Protocol Methods

initialize

Establishes a new MCP session.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "serverInfo": {
      "name": "fabric-mcp-gateway",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": { "listChanged": true }
    },
    "instructions": "..."
  }
}

The response includes an Mcp-Session-Id header for subsequent requests.

tools/list

Returns all available tools. A session opened with ?mode=discovery (on either URL) gets three meta-tools instead, search_tools, get_tool_schema and call_tool, which find, describe and run the same tools; see Discovery Mode.

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

Response includes:

• Platform tools (fabric_*): always present, including the six coding-instruction tools below
• Connected server tools ({prefix}__{tool}): from your MCP server connections

Connected tools include _meta saying whether a call needs runtime authority:

{
  "name": "linear__create_issue",
  "description": "[Linear] Create a new issue",
  "inputSchema": { "..." },
  "_meta": {
    "requiresAuthority": true,
    "providerAuthorityStatus": "missing",
    "providerKey": "linear"
  }
}

requiresAuthority is false for a tool the gateway treats as read-only, which runs without a grant; such a tool carries no providerAuthorityStatus. providerAuthorityStatus is granted when the session has any approved grant for the provider. It is not a promise for that tool, since a grant covers an access level and can be limited to some tools or to one request.

tools/call

Execute a tool.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "fabric_list_projects",
    "arguments": {
      "status": "ACTIVE",
      "limit": 10
    }
  }
}

A connected server tool that writes needs active authority; a read-only one runs without it:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "linear__create_issue",
    "arguments": { "project": "ABC", "title": "Example issue" }
  }
}

If not authorized, returns:

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"error\":\"Authority required\",\"action\":\"request_authority\",\"providerKey\":\"linear\"}"
    }],
    "isError": true
  }
}

Coding Instruction Tools

A project's published coding instructions are served through six platform tools. Each requires a scope on the credential: a call from a key or sign-in without it is refused with an error naming the scope, and the codingInstructions field on fabric_list_projects and fabric_get_project is omitted for a credential that cannot read the instructions.

instructions:write reaches only the proposal path, which is what a project reader can already do in the Coding Instructions tab. There is no scope and no argument that publishes from the gateway: a proposal is approved by a person who can edit the instructions, and on a project that syncs from a repository it becomes a commit on the proposer's own branch and a pull request there.

A sign-in grants mcp:read instructions:read instructions:write (the scope in the 401 challenge above). instructions:publish is a separate authority that only an organization API key created for it carries, and it is not reachable from the gateway.

Living Memory writes

Four tools read and put plain files in the Living Memory folders a project administrator named, without a local clone. Files never reach the repository from the agent: Fabric commits them with the repository integration's own credential.

memory:write is the one scope that can land a commit without review: on a folder set to direct push the files are committed to the synced branch, and elsewhere a pull request is opened and the files are not in Living Memory until a person merges it. A direct push that loses a race with another write that reached the branch first is retried on the new branch tip; only a branch that refuses the push (branch protection, a server hook, or missing write permission) turns the write into a pull request with reason protected. memory:write is never part of a default sign-in, so a coding tool signed in to the gateway cannot write. The Fabric CLI asks for it by name when it signs in, the person approves it, and the CLI's session hooks deliver the files. The three reads also accept mcp:read, since they show only what the Context tab shows a reader (a coding tool's default sign-in can list and read memory files but not write them). Coding instructions can never be written this way. Every call re-checks the person's permission on the project: adding context to write, reading it to read.

CLI Discovery

Each deployment serves its own build of the Fabric CLI, so a person can run it straight from a URL and the CLI they run is the one written for the server they talk to.

GET https://your-fabric.com/.well-known/fabric-cli.json

{
  "version": "0.4.0",
  "spec": 1,
  "integrity": "sha512-…",
  "minSupported": "0.4.0",
  "nodeRange": ">=22",
  "origin": null,
  "tarball": "https://your-fabric.com/cli/fabric-0.4.0-0123456789.tgz"
}

Baking an origin in is optional. The build takes it from FABRIC_CLI_ORIGIN, then NEXT_PUBLIC_SITE_URL, then APP_URL; it never reads what Vercel supplies, because a preview's address is a per-deployment host and the production domain would be baked into a staging build. With none set the CLI is still packed, origin is null, and the build says so in one line. FABRIC_CLI_REQUIRE_ORIGIN=1 makes a missing origin fatal for an operator who wants the build to refuse. The Connect dialog writes --base-url <the page's address> into its line unless origin is that address.

The document is public and answered with Cache-Control: public, max-age=60 and an open CORS header. A deployment built without the pack step answers 404 with { "error": "cli_not_served" }, and the Connect dialog then offers only the MCP entries.

Authority Management API

The following oRPC procedures manage authority sessions from the Fabric UI/API:

List Authority Sessions

GET /api/rpc/mcp.authority.list

Parameters:

Get Authority Session

GET /api/rpc/mcp.authority.get

Approve Authority Session

POST /api/rpc/mcp.authority.approve

Deny Authority Session

POST /api/rpc/mcp.authority.deny

Revoke Authority Session

POST /api/rpc/mcp.authority.revoke

HTTP Methods

Error Codes

Rate Limits

Standard API rate limits apply. The gateway does not add additional rate limiting beyond what the underlying MCP servers enforce.

Stateless Mode, Durable Execution, and MCP Apps

Stateless Requests

Clients that do not persist Mcp-Session-Id across requests (such as serverless workers, one-shot CLI invocations, or stateless desktop bridges) can send X-Mcp-Stateless: true or append ?stateless=1 to /mcp or /api/mcp-gateway. Each request is authenticated and executed independently without requiring an initialize handshake first.

Idempotent Durable Tool Calls

tools/call requests can opt into Fabric's 24-hour database-backed idempotency store:

• Headers: X-Mcp-Durable: true and optional X-Mcp-Idempotency-Key: <key>
• JSON-RPC _meta: { "_meta": { "durable": true, "idempotencyKey": "<key>" } }
• Tool arguments: _durable: true and optional _idempotencyKey: "<key>"

The gateway binds a receipt to the authenticated organization, authenticated user, credential identity, bound or pinned project, selected server or MCP configuration, tool name, key, and a canonical SHA-256 hash of the tool arguments. It claims that receipt before running the tool. Reusing the same key and arguments never runs a completed call again. When the tool's stored result is safe to return, the gateway replays it. Otherwise it returns a non-error completion receipt with the execution ID and completion time, sets _meta.durableExecution.resultWithheld: true, and directs the client to the matching get/list tool for current state without including the stored result. Reusing the key with different arguments is refused, and a live RUNNING call asks the client to retry later. Failed and expired receipts can be reclaimed; a RUNNING receipt becomes stale and reclaimable after 10 minutes.

An organization is required. Without an explicit key the tool still runs, but _meta.durableExecution reports deduplicated: false, stored: false, and reason: "no_idempotency_key"; the gateway does not derive a key. Metadata reports the truthful fabric-idempotency-store (or inline) engine, receipt executionId, status, replay and storage state, and timestamps. If saving the completion receipt fails after the tool succeeds, the gateway returns the tool result and reports that it was not stored.

Interactive MCP Apps (ui://fabric/*)

The gateway advertises the standard resources capability, attaches _meta.ui.resourceUri to supported tools/call results, and serves self-contained text/html;profile=mcp-app views via resources/list and resources/read:

Next Steps