Deploy the agent behind the Gateway

Mount the app

Either:

• Select it during onboarding, or
• Already have an mdk.yaml? Add it by hand

A Select it during onboarding

Run mdk onboard and select mdk-app-agent from its app catalog. mdk onboard's wizard supports creating a compliant mdk.yaml from scratch, interactively. It installs @tetherto/mdk-app-agent from its public repository and writes its spec.apps entry with mount: /.

B Add it to an existing mdk.yaml

Already have one from a previous onboarding run? Add the app under spec.apps by hand, with mount: / and the model provider, the MCP url, and the approval timeout under agent. The app resolves from node_modules/@tetherto/mdk-app-agent, and it is not on npm, so install it from its repository first, from the project directory:

npm install github:tetherto/mdk-app-agent

Commit the lockfile, for the reason in the note under option A. For example, a standalone gateway carrying just this app, reaching across to the MVP site example's MCP tool server:

apiVersion: mdk/v1
kind: Stack
metadata:
  name: agent-gateway
spec:
  workers: []
  gateway:
    port: 3847
  apps:
    - name: agent
      package: "@tetherto/mdk-app-agent"
      mount: /
      config:
        agent:
          provider: { kind: qvac, model: qwen3-4b, baseURL: http://127.0.0.1:11500/v1 }
          mcp: { url: http://127.0.0.1:3101/mcp }
          approvalTimeoutMs: 120000

1.2 Run it

Once the mdk.yaml names the app, either way, write the access policy before the first run:

mdk rbac init

mdk run refuses a stack whose spec.rbac binds nobody, because the Kernel would boot with nobody able to administer it. mdk rbac init writes the starter policy: an admin role, the CLI bound to it, and the Gateway and MCP server bound to read policy. Step 4 of the security blueprint covers what it writes and how to change it.

Then run mdk run. It starts the app in its own runtime process and the Gateway forwards the agent routes to it.

A stack built for just this app declares no Workers, so mdk run boots a Kernel it never actually uses (it only proxies chat to the MVP site's separate MCP server) alongside the app and the Gateway.

Give the agent a service account

mdk run mcp checks every agent against spec.rbac, so the agent signs in to it as its own service account. Without one, creating a session answers 503 ERR_AGENT_UNAVAILABLE: the MCP server at <url> answered 401. The MVP site example's MCP tool server on 3101 checks no token: against it, skip this step.

2.1 Create the account

With the stack running, from the project directory:

mdk sa add operator-agent

This writes the agent's credential to .mdk/credentials/agents/operator-agent.json, readable by you only, and registers its public key with the running Kernel.

2.2 Grant it the tools it may call

Bind the account to a role in mdk.yaml, beside the roles and bindings mdk rbac init wrote. An MCP tool generated from an app route needs the route's resource, <app>/<path>, and verb, so this role lets the agent call every read route of an ops app:

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

Apply the policy:

mdk rbac apply

Connect an AI agent over MCP covers how a route maps to a resource and a verb.

2.3 Point the agent at the account

Add the credential under agent.mcp, with the stack's Gateway, where the account signs in. The app runs from the project directory, so the path is relative to it:

      config:
        agent:
          provider: { kind: qvac, model: qwen3-4b, baseURL: http://127.0.0.1:11500/v1 }
          mcp:
            url: http://127.0.0.1:3947/mcp
            credential:
              file: .mdk/credentials/agents/operator-agent.json
              gatewayUrl: http://127.0.0.1:3847
          strictToolGating: false
          capability: mid
          approvalTimeoutMs: 120000

The agent sends an access token on every MCP request and renews it before it expires. Tools generated from app routes carry no agent contract, so strictToolGating: false with capability: mid (or large) is what admits them.

2.4 Restart and start the MCP server

Restart mdk run so the app reads its new config, then start the MCP server in a second terminal:

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

mdk run never starts it. It listens on spec.mcp.port, by default the Gateway's port plus 100.

Create a session and send a message

Use the port your mdk.yaml gave the gateway: 3847 in the example above. Note that the MVP site's own gateway (3000) never carries the agent app; this is a separate gateway, reaching across to the MVP site's MCP tool server on 3101.

Sign in first. The access token comes back in the response body; every call below carries it.

TOKEN=$(curl -s -X POST http://localhost:<port>/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"<name>","password":"<password>"}' | jq -r .accessToken)

curl -X POST http://localhost:<port>/agent/sessions \
  -H "Authorization: Bearer $TOKEN"
# {"sessionId":"..."}

curl -N -X POST http://localhost:<port>/agent/sessions/<id>/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"text":"how many miners are on the site?"}'

The response streams as text/event-stream. A read-only question ends in tool_call, tool_result, token, and done events, each stamped with the turn's turnId and a monotonic seq.

Approve a write

A write action pauses the turn instead of running it:

event: pending_approval
data: {"type":"pending_approval","name":"act_device","args":{"ref":"whatsminer-0","action":"reboot"},"approvalId":"..."}

Decide it from the paused stream's approvalId:

curl -X POST http://localhost:<port>/agent/sessions/<id>/approvals/<approvalId> \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"approved":true}'

Approving resumes the same stream: the tool runs for real, and the turn continues to its token and done events. Rejecting resolves to false, and the write never runs. Letting the approval window (approvalTimeoutMs) expire blocks the write the same way. With @tetherto/mdk-agent 0.13.1 and an mdk-app-agent build that depends on it, the tool_result then reads (no operator decision — approval expired, not executed), and the agent says no approval arrived in time. Earlier builds, including the 0.13.0 agent, report an expired approval as an operator rejection. Disconnecting while an approval is pending ends the turn: the write never runs, and the stream sends no tool_result.