Gatekyper MCP guide

Agent access without provider secrets

Gatekyper exposes JSON-RPC 2.0 over streamable HTTP. An MCP session maps to a known actor and permission level; every tool invocation is recorded with redacted arguments.

Create and protect an MCP session

An owner or administrator creates an MCP session for an existing actor and chooses permission level 1, 2, or 3. The resulting mcp_... session token is shown once and stored as a hash.

Level 1 · Read: Capability discovery, personal token metadata, personal usage, token budget status, and denial explanations.
Level 2 · Request: Everything in Level 1 plus temporary token requests and request-status polling. This is the normal agent default.
Level 3 · Template: Everything in Level 2 plus auto-approval only when the request fits the implemented bounded development template.

Transport and authentication

Endpoint: POST /mcp on the MCP service.
Protocol: JSON-RPC 2.0 with MCP protocol version 2025-06-18.
Authentication: Authorization: Bearer <MCP session token>.
Implemented methods: initialize, ping, tools/list, and tools/call.
Notifications: Requests without an id are accepted as notifications and return HTTP 202 with no body.

initialize

curl http://127.0.0.1:4200/mcp \
  -H "Authorization: Bearer ${GATEKYPER_MCP_SESSION_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "example-agent", "version": "1.0.0"}
    }
  }'

The shell variable must contain the display-once MCP session token created for this actor. It is not a Gate Token and cannot call the provider gateway.

Implemented tools

gatekyper.list_capabilities: Lists capabilities from active provider integrations and indicates whether this session would require approval.
gatekyper.list_my_tokens: Returns this actor’s token metadata and remaining daily budget where one exists. It never returns token plaintext.
gatekyper.get_my_usage: Returns this actor’s request count and estimated cost for today, seven days, or thirty days.
gatekyper.get_budget_status: Returns limits, spent, reserved, remaining, mode, status, and expiration for one token owned by this actor.
gatekyper.explain_denial: Looks up a denial by request identifier and returns its safe reason and requested provider, capability, and model.
gatekyper.request_token: Creates a structured request for a scoped temporary Gate Token; it may auto-approve only at Level 3 within the safe template.
gatekyper.get_request_status: Polls a request and releases the approved token plaintext exactly once to the same requesting actor.

Call a read tool

The server advertises only tools allowed by the current MCP session permission level.

list tools

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

check usage

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "gatekyper.get_my_usage",
    "arguments": {"window": "today"}
  }
}

Successful tool results are returned as an MCP text content item containing formatted JSON. Tool validation or authorization errors use an MCP result with isError: true.

Request a temporary Gate Token

A Level 2 or 3 session can submit the work’s purpose and proposed boundary:

tools/call arguments

{
  "name": "gatekyper.request_token",
  "arguments": {
    "project": "example-project",
    "purpose": "Summarize the approved test documents.",
    "environment": "dev",
    "provider": "openai",
    "capabilities": ["ai.chat"],
    "models": ["gpt-4.1-mini"],
    "requested_budget_usd": 1,
    "requested_expiration_hours": 8,
    "estimated_calls": 12,
    "task_id": "task_example"
  }
}

Level 2: approval required

The tool creates an access request and returns its identifier. A human reviews it in the dashboard. The agent polls gatekyper.get_request_status.

Level 3: bounded auto-approval

The implemented safe template requires all of the following:

development environment;
OpenAI, Anthropic, or OpenRouter;
only chat or embeddings capabilities;
a daily budget no greater than 1 USD; and
expiration no longer than 24 hours.

Anything outside every bound becomes a human approval request rather than partially broadening the template.

Collect an approved token once

tools/call

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "gatekyper.get_request_status",
    "arguments": {"access_request_id": "req_example"}
  }
}

While pending, the tool reports that it is waiting for human approval.
If denied or expired, it returns that status and no token.
On the first poll after approval, the same actor receives token plaintext, token identifier, and expiration.
Later polls report that the token was already collected and return metadata only.

Pending approved token material is encrypted for one-time collection with a key derived from the application secret. The MCP service does not receive the provider-credential encryption key.

MCP safety rules

Map every session to a distinct known actor.
Use Level 1 when the agent only needs visibility.
Prefer Level 2 when a person should approve all new authority.
Protect the MCP session token like any other credential and revoke the session when it is no longer needed.
Keep the MCP interface private unless it has an intentionally designed remote-access boundary.
Review MCP invocation and access-request audit activity.
Never pass a provider key or Gate Token as a tool argument.