MCP: connect an agent

Forge speaks MCP at /mcp on your instance. There is nothing to deploy and no proxy to configure: the tool list is the registry, and the gate behind it is the kernel’s.

1. Point an agent at it

With Claude Code:

export FORGE_TOKEN='fopk_…'

claude mcp add --transport http forge https://your-instance.example/mcp \
  --header "Authorization: Bearer $FORGE_TOKEN"

claude mcp list

Any MCP client works — it is HTTP with a bearer token. Speaking to it by hand:

curl -X POST https://your-instance.example/mcp \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-06-18","capabilities":{},
        "clientInfo":{"name":"my-agent","version":"1"}}}'

{ "result": { "protocolVersion": "2025-06-18", "serverInfo": { "name": "forge-mcp", "version": "1.0.0" } } }

Both accept values are required

The endpoint may answer as JSON or as a stream, so the header must offer application/json, text/event-stream. An MCP client sends this for you; curl does not.

2. The tool list is the key’s scopes

This is the part worth pausing on.

curl -X POST https://your-instance.example/mcp … -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

A key carrying catalog.admin.read, logistics.read and order.read sees 60 tools, all of them reads. Not sixty out of a longer list it must be trusted not to call — sixty is what exists for that credential.

Issue a key with write scopes and the write tools appear. Revoke a scope and they leave. The agent does not get told what it may do; it is only handed what it may do, and the scope check is the kernel’s, so there is no proxy rule that could drift from it.

That is the whole reason it is safe to hand an agent a key here: the blast radius is a property of the credential, and you set it when you mint it.

3. Call something

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "read.products",
    "arguments": { "store": "sto_…", "limit": 1, "projection": "feed" }
  }
}

Tools carry the registry’s own names and the registry’s own schemas, so an agent that can read the tool list can construct a valid call without being taught the API.

Ask for projection=feed

The default projection is full, and ten products of it runs to tens of thousands of characters — enough to swallow an agent’s context for a list it only needed titles from. feed is the projection built for this.

store takes the store id, not a handle.

4. Refusals reach the agent

Reaching past the key’s scopes returns the kernel’s own forbidden, naming the scope. An agent sees a refusal it can reason about rather than an empty result it will assume means “there is nothing there”.

And every call is in the audit trail under the key’s name — ERP Nimbus, not “someone”. Including the refusals. See identity and scopes.

What is not here yet

The shopper journey — creating a cart, placing an order — is not in the tool list today. Those tools exist and are gated on the server knowing which store it is serving, and no production entry point supplies that yet. A tenant credential can serve several stores, so where that answer comes from is a design question rather than a wire to connect.

Until it lands, an agent on this endpoint reads the catalogue, orders and logistics, and writes through the operator commands its key carries.

Next

• Connect an ERP — the same idea without an agent.
• Issue & rotate API keys — how to make the narrow key this page assumes.