Connect an AI agent over MCP

Create the agent's service account

npx mdk sa add operator-agent

This writes the agent's Ed25519 credential to .mdk/credentials/agents/operator-agent.json, readable by you only, and registers its public key with the running Kernel. The account can't call anything yet.

Grant it routes in spec.rbac

Add a role to mdk.yaml and bind the agent to it, beside the roles and bindings mdk onboard or mdk rbac init wrote:

spec:
  rbac:
    roles:
      - name: ops-viewer
        rules:
          - resources: [ops/*]
            verbs: [get, list]
    bindings:
      - role: ops-viewer
        subjects:
          - kind: ServiceAccount
            name: operator-agent

An app route's resource is <app>/<path>: the app's name in spec.apps, then the route's path. GET /api/ops/summary in the ops app is ops/api/ops/summary, so ops/* covers every route of the app. The verb is the route's verb, or follows its method: GET is get, POST is create, PUT and PATCH are update, DELETE is delete.

Apply the policy:

npx mdk rbac apply

The running Kernel switches to the new policy. Nothing restarts, the MCP server included.

Start the MCP server

In a second terminal:

npx mdk run mcp    # http://localhost:3947/mcp

It listens on spec.mcp.port, by default the Gateway's port plus 100. Only routes marked "safety": "read-only" become tools unless it starts with --allow-write.

Get the agent a token

For a quick test, print one. It lasts 10 minutes:

TOKEN=$(npx mdk sa token operator-agent)

An agent that runs longer signs itself in with its credential and renews the token before it expires. @tetherto/mdk-identity does both, through the Gateway's POST /auth/token. Ask the token source for headers on every POST /mcp:

const fs = require('node:fs')
const { ServiceAccountTokenSource, gatewayTokenRequest } = require('@tetherto/mdk-identity')

const { name, privateKeyPem } = JSON.parse(fs.readFileSync('.mdk/credentials/agents/operator-agent.json', 'utf8'))
const source = new ServiceAccountTokenSource({
  name,
  privateKey: privateKeyPem,
  request: gatewayTokenRequest('http://localhost:3847')
})

async function mcpHeaders () {
  return { authorization: `Bearer ${await source.getToken()}` }
}

Call the tools

List them:

curl -s -X POST localhost:3947/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -H "authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The result lists ops_summary, named after the route's id, with the route's description as its own. Call it:

curl -s -X POST localhost:3947/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -H "authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ops_summary","arguments":{}}}'

The tool returns the controller's JSON, {"ok":true,"kernelConnected":true,"workerCount":1,"deviceCount":1,…}: the same body the Gateway returns for GET /apps/ops/api/ops/summary with the same token.

To connect an MCP client, point it at http://localhost:3947/mcp with the authorization header. A client with a fixed header needs a fresh token every 10 minutes; one that runs your code can use the token source above.