MCP (Model Context Protocol)

Overview

Agent Sentinel exposes two MCP protocol endpoints: /mcp for agents executing governed tools and /mcp/admin for platform administration. Both use JSON-RPC 2.0 over stateless streamable HTTP with JSON responses, without persistent sessions or an SSE stream. The older /api/v1/mcp/* REST facade is documented below.

Endpoint and auth

Send requests to POST /mcp with Authorization: ApiKey <agent-bound-key>, Content-Type: application/json and Accept: application/json, text/event-stream. Only agent-bound API keys are accepted. The organization and agent identity come from the key; X-Sentinel-Agent-Id cannot override them. A user session or unbound key receives HTTP 403 with top-level reason_code: "agent_bound_key_required". Missing authorization receives HTTP 401. The server supports initialize, ping, tools/list and tools/call. Use an MCP client to initialize and negotiate the protocol before calling tools. tools/list returns only enabled governed tools in the caller’s organization, ordered by name; it does not expose the admin tools. For example, after registering the send tool below, list tools:

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

The response uses MCP’s inputSchema field (the registry uses input_schema):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [{
      "name": "send",
      "description": "send description",
      "inputSchema": {
        "type": "object",
        "properties": {"to": {"type": "string"}},
        "required": ["to"]
      }
    }]
  }
}

Registering governed tools

Operators register executable targets through /api/v1/governed-tools, using a user session. All registry routes refuse API keys, bound or unbound. Reads require organization membership; writes require OWNER or ADMIN. Tools belong to the active organization; another organization’s tool returns 404. Send this JSON body to POST /api/v1/governed-tools (201 on success):

{
  "name": "send",
  "description": "send description",
  "input_schema": {
    "type": "object",
    "properties": {"to": {"type": "string"}},
    "required": ["to"]
  },
  "impact": "low",
  "estimated_cost_usd": 0.25,
  "tags": ["email"],
  "target_url": "https://tools.example.com/run?v=1",
  "target_method": "POST",
  "timeout_seconds": 5,
  "enabled": true
}

The target URL is illustrative: register an actual endpoint you operate. Names must match [A-Za-z0-9_.-]{1,64} and be unique within the organization. input_schema must be an object schema of at most 16 KiB serialized. Only POST targets are supported; timeouts range from 1 to 30 seconds (default 10). Use GET on the collection or /{tool_id} to inspect registrations, PATCH /{tool_id} to update and DELETE /{tool_id} to remove them. Target URLs must use HTTPS, contain no userinfo and resolve only to global addresses. Loopback, private, link-local (including cloud metadata), multicast, reserved and unspecified addresses are refused. HTTP is permitted only with ENVIRONMENT=local. GOVERNED_TOOL_ALLOW_PRIVATE_TARGETS bypasses address checks only when ENVIRONMENT=local; it is ignored elsewhere. Targets are checked at registration and again at execution. For credential binding and injection, see AgentVault Credentials.

tools/call lifecycle

Call a registered tool by name:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send",
    "arguments": {"to": "a@example.com", "note": "héllo"}
  }
}

Validate before writes. The tool must be enabled in the caller’s organization. Arguments must be a JSON object, contain only finite numbers, fit within 64 KiB as canonical JSON and satisfy input_schema. Invalid or unresolvable schema references are refused; remote schemas are never fetched. Optional _meta.run_id and _meta.approval_request_id must be UUIDs.
Ask the gateway. The executor hashes canonical arguments (sorted keys, compact UTF-8 JSON) into inputs_digest. Action name, impact, cost and tags come from the tool registration. The gateway can allow, deny or require approval. Denial and approval-required decisions never contact the target.
Verify the decision token. An allow executes only if its token verifies and matches the organization, agent, action and input digest.
Execute a DNS-pinned POST. The executor revalidates DNS and connects to a checked address while preserving the original Host and TLS SNI. It posts the canonical arguments with X-Sentinel-Decision-Token. Redirects are not followed, compressed responses are refused, and response reading stops at 1 MiB.
Record and reconcile. A signed tool_result ledger row records status, response byte count and SHA-256, never the response body. Recording and reservation reconciliation share a transaction; an unverifiable signature prevents that transaction from committing. Whenever the target returned a response status, including a non-2xx status or a failure while reading the body, the reservation reconciles the registered estimated cost. Only a call that never received a response (refused target, connection failure, timeout before headers) reconciles zero. Retries of failed calls therefore consume budget. After validation, the decision, execution and recording task survives caller cancellation.

For a target returning delivered ✓, success is an HTTP 200 JSON-RPC result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "delivered ✓"}],
    "isError": false
  }
}

Tool refusals also use HTTP 200, with result.isError: true and result.structuredContent.reason_code. For example, passing {"to":5} fails the registered schema:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "tool arguments do not match the input schema: 5 is not of type 'string'"}],
    "structuredContent": {"reason_code": "arguments_invalid"},
    "isError": true
  }
}

Approvals

When the gateway returns require_approval, the tool result has isError: true and structuredContent containing decision, reason_code and approval_request_id. Its text directs the caller to poll GET /api/v1/approvals/{approval_request_id}/poll. No target request has occurred yet. After approval, retry the same tool with the same arguments, passing the returned UUID in params._meta.approval_request_id:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send",
    "arguments": {"to": "a@example.com", "note": "héllo"},
    "_meta": {"approval_request_id": "12345678-1234-4234-8234-123456789abc"}
  }
}

The UUID above is illustrative; use the returned approval ID. Before redemption, the executor checks the organization, action and argument digest. A mismatch returns approval_inputs_mismatch without consuming the approval. Approval redemption is single-use; pending, expired, rejected or already-redeemed approvals cannot authorize execution. See the Approvals API.

Limits

Surface	Limit	Failure
Request body on both protocol mounts	1 MiB (1,048,576 bytes), enforced before authentication	HTTP 413, JSON-RPC `-32600`, `Request body too large`
JSON nesting on both mounts	At most 64 levels	HTTP 400, JSON-RPC parse error `-32700` after authentication
Governed tool arguments	64 KiB (65,536 bytes) of canonical JSON	Tool result `arguments_too_large`
Governed target response	1 MiB (1,048,576 bytes)	Tool result `tool_response_too_large`

Malformed JSON also produces -32700. Compressed target responses are refused with tool_response_encoded rather than decompressed.

Error reason codes

These are all reason-code constants defined by the governed tool executor. Read them from result.structuredContent.reason_code; execution failures may also include status_code (null if no response was received).

Reason code	Meaning
`tool_not_found`	Tool is unknown, disabled or outside the caller’s organization.
`arguments_not_object`	Arguments are not a JSON object.
`arguments_not_finite`	Arguments contain NaN or infinity.
`arguments_too_large`	Canonical arguments exceed 64 KiB.
`arguments_invalid`	Arguments do not satisfy the registered schema or contain invalid Unicode.
`tool_schema_invalid`	Schema is invalid or contains an unresolvable reference.
`tool_config_invalid`	Tool registration cannot form a valid gateway request.
`invalid_run_id`	`_meta.run_id` is not a UUID.
`invalid_approval_request_id`	`_meta.approval_request_id` is not a UUID.
`approval_inputs_mismatch`	Approval does not match the organization, tool and arguments.
`approval_not_redeemable`	Approval redemption was refused (fallback if the gateway supplies no specific code).
`gateway_refused`	Gateway authorization was refused (fallback if it supplies no specific code).
`decision_token_invalid`	Allow token does not verify or match this call; target was not run.
`tool_target_rejected`	Target failed call-time URL or address checks; target was not run.
`tool_response_too_large`	Target response exceeds 1 MiB.
`tool_response_encoded`	Target returned a content-encoded response.
`tool_transport_error`	Target could not be reached or the request timed out.
`tool_http_error`	Target returned a non-2xx status, including redirects.
`result_signing_failed`	Tool ran but its result could not be signed; recording transaction did not commit.
`tool_call_failed`	An internal platform failure prevented completing the call.

Gateway decisions and refusals can additionally pass through gateway reason codes, such as no_policy_for_write, monthly_budget_exceeded, group_budget_exceeded and kill_switch_active. Denials include decision: "deny"; approval-required results include decision: "require_approval" and approval_request_id. Transport and admin errors have separate meanings:

HTTP status / code	Meaning
401	Missing or invalid authentication.
403 `agent_bound_key_required`	`/mcp` requires an agent-bound API key.
403 `agent_bound_key_forbidden`	`/mcp/admin` refuses agent-bound keys before JSON-RPC handling. The legacy REST facade also refuses them.
413 / JSON-RPC `-32600`	Request body exceeds 1 MiB on either protocol mount.
400 / JSON-RPC `-32700`	Invalid JSON or nesting deeper than 64 levels on either mount.
200 / tool result `user_session_required`	An unbound key tried to call a management tool on `/mcp/admin`.
200 / tool result `tool_not_found`	Admin tool is unknown or has no handler.
200 / tool result `tool_failed`	An admin tool handler reported failure.

Authentication errors on the protocol mounts are ordinary JSON with a top-level reason_code when provided, rather than JSON-RPC tool results.

Admin mount

Use POST /mcp/admin with a user session or an unbound API key and the same content and accept headers as /mcp. Agent-bound keys receive HTTP 403 agent_bound_key_forbidden, including for initialize and tools/list. This separate server identifies itself as agent-sentinel-admin. tools/list advertises only platform tools with implemented handlers. Unbound keys can list these tools and call read-only handlers such as list_runs; management handlers such as create_policy require a user session. Unknown and handler-less tools return tool_not_found before the management check (for example, get_policy and create_api_key are not advertised). For example, a user session can send:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {"name": "create_policy", "arguments": {"name": "Budget Control", "enabled": true}}
}

Successful admin calls return text containing JSON-serialized handler data and a structuredContent object containing the handler’s success, data, error and metadata, with isError: false. An unbound key calling this management tool instead gets isError: true with structuredContent.reason_code: "user_session_required". These handlers manage platform state; they do not execute registered governed targets through the /mcp lifecycle.

Legacy REST facade

The remaining examples document the legacy /api/v1/mcp/* REST facade, not the JSON-RPC protocol endpoints. Use /mcp for agent-bound governed tool execution and /mcp/admin for protocol-based administration. Agent-bound keys are refused with HTTP 403 agent_bound_key_forbidden on the legacy facade’s execution routes: POST /api/v1/mcp/call, GET /api/v1/mcp/resources/{uri} and POST /api/v1/mcp/prompts/{name}. The discovery listings (GET /api/v1/mcp/tools, /resources and /prompts) still accept them. Use a user session for management operations or an unbound key for permitted read-only operations. The following REST payloads retain their legacy field names and envelopes.

Legacy overview

The REST facade exposes platform functionality as:

Tools: Actions LLMs can execute (create policies, approve actions, query data)
Resources: Data LLMs can read (runs, approvals, stats, policies)
Prompts: Pre-configured workflows (analyze costs, review approvals, generate reports)

This enables LLMs to autonomously manage and monitor the Agent Sentinel platform.

Authentication: management requires a user session

The legacy REST endpoints accept a user session (console login JWT) or an unbound API key, but unbound API keys can only call read-only tools and prompts. An agent must not be able to edit its own governance.

Management tools: create_policy, update_policy, delete_policy, approve_action, reject_action, create_api_key, revoke_api_key. Management prompt: create_budget_policy. These require a user session. Any API key, bound to an agent or not, gets 403 with "management operations require a user session, not an API key".
Read-only tools and prompts (listing, get_*, stats, compliance, the advisor tools including draft_policy_update, which never applies its draft) stay available to unbound API keys.
The rule is default-deny: a tool or prompt that is not explicitly classified read-only is refused to API keys.
GET /api/v1/mcp/tools and GET /api/v1/mcp/prompts list everything, with requires_user_session: true on management entries.

Legacy endpoints

List available tools

GET /api/v1/mcp/tools

Returns all available MCP tools with schemas:

{
  "tools": [
    {
      "name": "create_policy",
      "description": "Create a new policy with budgets and rules",
      "input_schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "description": {"type": "string"},
          "enabled": {"type": "boolean"},
          "session_budget": {"type": "number"},
          "run_budget": {"type": "number"},
          "denied_actions": {"type": "array", "items": {"type": "string"}},
          "rate_limits": {"type": "object"}
        },
        "required": ["name"]
      }
    },
    {
      "name": "list_runs",
      "description": "Get list of agent runs with optional filters",
      "input_schema": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "enum": ["running", "completed", "failed"]},
          "min_cost": {"type": "number"},
          "agent_id": {"type": "string"},
          "limit": {"type": "integer"}
        }
      }
    },
    {
      "name": "get_pending_approvals",
      "description": "Fetch all pending approval requests",
      "input_schema": {"type": "object"}
    },
    {
      "name": "approve_action",
      "description": "Approve a pending action",
      "input_schema": {
        "type": "object",
        "properties": {
          "approval_id": {"type": "string"},
          "approver_email": {"type": "string"},
          "notes": {"type": "string"}
        },
        "required": ["approval_id", "approver_email"]
      }
    },
    {
      "name": "reject_action",
      "description": "Reject a pending action",
      "input_schema": {
        "type": "object",
        "properties": {
          "approval_id": {"type": "string"},
          "approver_email": {"type": "string"},
          "notes": {"type": "string"}
        },
        "required": ["approval_id", "approver_email"]
      }
    },
    {
      "name": "get_agent_stats",
      "description": "Get comprehensive statistics for an agent",
      "input_schema": {
        "type": "object",
        "properties": {
          "agent_id": {"type": "string"}
        },
        "required": ["agent_id"]
      }
    },
    {
      "name": "export_ledger",
      "description": "Export activity ledger in JSON/JSONL/CSV format",
      "input_schema": {
        "type": "object",
        "properties": {
          "format": {"type": "string", "enum": ["json", "jsonl", "csv"]},
          "start_date": {"type": "string"},
          "end_date": {"type": "string"},
          "agent_id": {"type": "string"}
        },
        "required": ["format"]
      }
    }
  ]
}

Execute MCP tool

POST /api/v1/mcp/call

Request body:

{
  "tool_name": "create_policy",
  "arguments": {
    "name": "Budget Control",
    "description": "Limit costs for dev environment",
    "enabled": true,
    "session_budget": 5.0,
    "run_budget": 1.0,
    "denied_actions": ["delete_production_db"]
  }
}

Response:

{
  "success": true,
  "data": {
    "policy_id": "policy_abc123",
    "name": "Budget Control",
    "enabled": true,
    "created_at": "2024-12-28T14:30:00Z"
  },
  "error": null,
  "metadata": {
    "execution_time_ms": 45
  }
}

List available resources

GET /api/v1/mcp/resources

Returns all available MCP resources:

{
  "resources": [
    {
      "uri": "agentsentinel://runs/latest",
      "name": "Latest Run",
      "description": "Get the most recent run",
      "mime_type": "application/json"
    },
    {
      "uri": "agentsentinel://approvals/pending",
      "name": "Pending Approvals",
      "description": "List all pending approval requests",
      "mime_type": "application/json"
    },
    {
      "uri": "agentsentinel://stats/dashboard",
      "name": "Dashboard Stats",
      "description": "Get aggregate dashboard statistics",
      "mime_type": "application/json"
    },
    {
      "uri": "agentsentinel://policies/active",
      "name": "Active Policies",
      "description": "List all enabled policies",
      "mime_type": "application/json"
    },
    {
      "uri": "agentsentinel://compliance/summary",
      "name": "Compliance Summary",
      "description": "Get compliance overview and status",
      "mime_type": "application/json"
    }
  ]
}

Get resource data

GET /api/v1/mcp/resources/{uri}

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "$AGENT_SENTINEL_URL/api/v1/mcp/resources/agentsentinel://stats/dashboard"

Response:

{
  "uri": "agentsentinel://stats/dashboard",
  "mime_type": "application/json",
  "data": {
    "total_runs": 1234,
    "total_actions": 45678,
    "total_cost_usd": 567.89,
    "success_rate": 0.95,
    "pending_approvals": 5,
    "interventions_24h": 23
  }
}

List available prompts

GET /api/v1/mcp/prompts

Returns all available prompt templates:

{
  "prompts": [
    {
      "name": "create_budget_policy",
      "description": "Guided workflow to create a budget policy",
      "arguments": [
        {
          "name": "agent_id",
          "description": "Agent ID to apply policy to",
          "required": false
        },
        {
          "name": "budget_usd",
          "description": "Budget amount in USD",
          "required": true
        }
      ]
    },
    {
      "name": "analyze_agent_costs",
      "description": "Analyze cost patterns for an agent over time",
      "arguments": [
        {
          "name": "agent_id",
          "description": "Agent ID to analyze",
          "required": true
        },
        {
          "name": "days",
          "description": "Number of days to analyze",
          "required": false
        }
      ]
    },
    {
      "name": "review_pending_approvals",
      "description": "Review and triage pending approval requests",
      "arguments": []
    },
    {
      "name": "compliance_audit_report",
      "description": "Generate a compliance audit report",
      "arguments": [
        {
          "name": "start_date",
          "description": "Report start date",
          "required": false
        },
        {
          "name": "end_date",
          "description": "Report end date",
          "required": false
        }
      ]
    }
  ]
}

Execute prompt template

POST /api/v1/mcp/prompts/{name}

Example:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "agent_id": "trading-bot",
      "days": 7
    }
  }' \
  "$AGENT_SENTINEL_URL/api/v1/mcp/prompts/analyze_agent_costs"

Response:

{
  "prompt": "analyze_agent_costs",
  "data": {
    "summary": "The trading-bot has spent $45.23 over 7 days across 1,234 actions. Top cost drivers: call_llm ($23.45, 456 calls), search_web ($12.34, 234 calls). Average cost per run: $0.37. Recommendation: Consider caching search results to reduce API calls.",
    "details": {
      "total_cost_usd": 45.23,
      "total_actions": 1234,
      "total_runs": 123,
      "avg_cost_per_run": 0.37,
      "top_actions": [
        {"action": "call_llm", "cost": 23.45, "count": 456},
        {"action": "search_web", "cost": 12.34, "count": 234}
      ]
    }
  }
}

Using the legacy facade with Claude

Give Claude access to Agent Sentinel via tool use:

from anthropic import Anthropic
import requests

# Fetch MCP tools
response = requests.get(
    f"{AGENT_SENTINEL_URL}/api/v1/mcp/tools",
    headers={"Authorization": f"Bearer {api_token}"}
)
mcp_tools = response.json()["tools"]

# Convert to Anthropic tool format
anthropic_tools = [
    {
        "name": tool["name"],
        "description": tool["description"],
        "input_schema": tool["input_schema"]
    }
    for tool in mcp_tools
]

# Give Claude access
client = Anthropic()
response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=4096,
    tools=anthropic_tools,
    messages=[{
        "role": "user",
        "content": "Check if there are any critical-priority approvals that have been pending for more than 5 minutes. If so, show me the details."
    }]
)

# Process tool calls
if response.stop_reason == "tool_use":
    for block in response.content:
        if block.type == "tool_use":
            # Execute MCP tool
            result = requests.post(
                f"{AGENT_SENTINEL_URL}/api/v1/mcp/call",
                headers={"Authorization": f"Bearer {api_token}"},
                json={
                    "tool_name": block.name,
                    "arguments": block.input
                }
            )
            print(result.json())

Using the legacy facade with OpenAI

from openai import OpenAI
import requests

# Fetch MCP tools
response = requests.get(
    f"{AGENT_SENTINEL_URL}/api/v1/mcp/tools",
    headers={"Authorization": f"Bearer {api_token}"}
)
mcp_tools = response.json()["tools"]

# Convert to OpenAI function format
openai_functions = [
    {
        "name": tool["name"],
        "description": tool["description"],
        "parameters": tool["input_schema"]
    }
    for tool in mcp_tools
]

# Give GPT access
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": "Create a policy to limit my development agent to $5 per run"
    }],
    functions=openai_functions,
    function_call="auto"
)

# Process function calls
if response.choices[0].message.function_call:
    function_call = response.choices[0].message.function_call
    # Execute MCP tool
    result = requests.post(
        f"{AGENT_SENTINEL_URL}/api/v1/mcp/call",
        headers={"Authorization": f"Bearer {api_token}"},
        json={
            "tool_name": function_call.name,
            "arguments": json.loads(function_call.arguments)
        }
    )

Legacy example workflows

Autonomous approval management

User: "Review all pending approvals and approve any low-risk actions that cost less than $1"

Claude uses MCP tools:
1. get_pending_approvals() → Returns 5 pending approvals
2. For each approval with risk_level="low" and cost < $1:
   - approve_action(approval_id, approver_email="claude@company.com", notes="Auto-approved: low risk, low cost")
3. Returns summary: "Approved 3 low-risk actions, 2 remain pending for human review"

Cost optimization analysis

User: "Analyze costs for all my agents and suggest policy changes to reduce spend"

Claude uses MCP tools:
1. list_runs() → Get all runs
2. For each unique agent_id:
   - get_agent_stats(agent_id) → Get cost breakdown
3. Analyzes patterns
4. create_policy() → Creates budget policies for high-cost agents
5. Returns report with recommendations

Compliance reporting

User: "Generate a compliance report for the last 30 days"

Claude uses MCP prompts:
1. execute_prompt("compliance_audit_report", {start_date: "2024-11-28", end_date: "2024-12-28"})
2. Returns formatted compliance report with:
   - Total actions logged
   - Human oversight events
   - Policy violations
   - Data retention status

Legacy best practices

Use prompts for complex workflows: Prompts encapsulate multi-step operations - use them instead of chaining multiple tool calls.

Secure API tokens: Unbound API keys only reach read-only tools on the legacy facade. Agent-bound keys are refused. Policy, approval and key management needs a user session.

Validate LLM decisions: For critical operations (approvals, policy changes), implement human-in-the-loop confirmation before executing MCP tool calls.

Cache tool schemas: Tool and resource lists change infrequently - cache them to reduce API calls.

Getting started

Concepts

SDK (Python)

AI tools

Platform API

Web Console

MCP (Model Context Protocol)

Overview

Endpoint and auth

Registering governed tools

tools/call lifecycle

Approvals

Limits

Error reason codes

Admin mount

Legacy REST facade

Legacy overview

Authentication: management requires a user session

Legacy endpoints

List available tools

Execute MCP tool

List available resources

Get resource data

List available prompts

Execute prompt template

Using the legacy facade with Claude

Using the legacy facade with OpenAI

Legacy example workflows

Autonomous approval management

Cost optimization analysis

Compliance reporting

Legacy best practices

See also