MCP Server Endpoints

Register and manage Model Context Protocol servers, verify agent access to tools, and expose OAuth 2.0 Protected Resource Metadata.

Register MCP Server

POST /api/v1/mcp/servers

Register an MCP server with Bulwark so agents can be authorized to call its tools.

Headers

• Authorization: Bearer <apiKey>
• X-Bulwark-Tenant: <tenant-id>

Body

{
  "name": "file-ops-server",
  "description": "File system operations for the workspace agent",
  "url": "https://mcp.example.com",
  "tools": [
    {
      "name": "read_file",
      "description": "Read a file by path",
      "scopes_required": ["files:read"]
    },
    {
      "name": "write_file",
      "description": "Write or overwrite a file",
      "scopes_required": ["files:write"]
    }
  ],
  "metadata": {
    "owner": "platform-team",
    "env": "production"
  }
}

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Unique server name within the tenant | | url | Yes | Base URL of the MCP server | | tools | No | Tool definitions with required scopes for authorization | | description | No | Human-readable description | | metadata | No | Arbitrary key-value metadata |

Response 201

{
  "data": {
    "server_id": "mcp_01j...",
    "name": "file-ops-server",
    "url": "https://mcp.example.com",
    "tools": [
      { "name": "read_file", "scopes_required": ["files:read"] },
      { "name": "write_file", "scopes_required": ["files:write"] }
    ],
    "created_at": "2026-03-30T00:00:00Z"
  }
}

List MCP Servers

GET /api/v1/mcp/servers

Headers

• Authorization: Bearer <apiKey>
• X-Bulwark-Tenant: <tenant-id>

Query Parameters

| Parameter | Description | |-----------|-------------| | limit | Results per page (default: 20, max: 100) | | cursor | Pagination cursor from previous response |

Response 200

{
  "data": [
    {
      "server_id": "mcp_01j...",
      "name": "file-ops-server",
      "url": "https://mcp.example.com",
      "tool_count": 2,
      "created_at": "2026-03-30T00:00:00Z"
    }
  ],
  "pagination": { "cursor": "...", "has_more": false }
}

Get MCP Server

GET /api/v1/mcp/servers/{id}

Response 200

{
  "data": {
    "server_id": "mcp_01j...",
    "name": "file-ops-server",
    "url": "https://mcp.example.com",
    "description": "File system operations for the workspace agent",
    "tools": [
      { "name": "read_file", "scopes_required": ["files:read"] },
      { "name": "write_file", "scopes_required": ["files:write"] }
    ],
    "metadata": { "owner": "platform-team", "env": "production" },
    "created_at": "2026-03-30T00:00:00Z"
  }
}

Delete MCP Server

DELETE /api/v1/mcp/servers/{id}

Removes the server registration. Agents with existing Biscuit tokens scoped to this server's tools will be denied on next introspection.

Response 200

{
  "data": {
    "server_id": "mcp_01j...",
    "deleted_at": "2026-03-30T14:00:00Z"
  }
}

Introspect Agent Token

POST /api/v1/mcp/introspect

Public endpoint — no admin credentials required. Called by MCP servers to verify that an incoming agent Biscuit token is valid and grants access to a specific tool.

Headers

• X-Bulwark-Tenant: <tenant-id>

Body

{
  "token": "<biscuit-token>",
  "tool": "write_file",
  "server_id": "mcp_01j..."
}

Response 200 — Authorized

{
  "data": {
    "authorized": true,
    "agent_id": "agent_01j...",
    "agent_name": "workspace-agent",
    "scopes": ["files:read", "files:write"],
    "trust_level": "medium",
    "session_id": "sess_01j...",
    "expires_at": "2026-03-30T14:00:00Z"
  }
}

Response 200 — Denied

{
  "data": {
    "authorized": false,
    "reason": "SCOPE_MISSING",
    "message": "Token does not include scope 'files:write'."
  }
}

Protected Resource Metadata

GET /api/v1/mcp/servers/{id}/metadata

Returns OAuth 2.0 Protected Resource Metadata per RFC 9728. MCP clients use this discovery document to determine which authorization server issues tokens for this resource.

Response 200

{
  "resource": "https://mcp.example.com",
  "authorization_servers": [
    "https://api.bulwarkauth.com"
  ],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["files:read", "files:write"],
  "introspection_endpoint": "https://api.bulwarkauth.com/api/v1/mcp/introspect"
}

This endpoint is unauthenticated and intended for public discovery.