GitHubDashboard
Docs/REST API

REST API Reference

The MCP Shield REST API allows you to programmatically manage providers, invoke MCP tools, configure policies, and query audit logs.

Base URL

https://api.mcpshield.com
bash

All API requests should be made to this base URL. The API is versioned via URL path (e.g., /v1/).

Authentication

Authenticate API requests using Bearer tokens in the Authorization header:

curl https://api.mcpshield.com/v1/mcps \
  -H "Authorization: Bearer mcp_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json"
bash

Token Types

User tokens (mcp_live_) are tied to a user session.
Service tokens (svc_live_) are for automation and CI/CD.

Authentication Guide

Quick Example

Invoke an MCP tool and receive a governed response:

Request
curl -X POST https://api.mcpshield.com/v1/mcps/github:list_repos/invoke \
  -H "Authorization: Bearer mcp_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "limit": 5
    }
  }'
Response
{
  "result": {
    "repositories": [
      {
        "name": "project-a",
        "visibility": "private",
        "updated_at": "2024-01-15T14:32:00Z"
      }
    ]
  },
  "governance": {
    "decision": "allow",
    "policy": "default-allow-read",
    "dlp_result": "passed",
    "audit_event_id": "evt_xxxxx"
  }
}

Endpoints

Authentication

POST/v1/auth/token

Exchange credentials for access token

POST/v1/auth/refresh

Refresh an access token

DELETE/v1/auth/token

Revoke a token

MCPs

GET/v1/mcps

List available MCP tools

GET/v1/mcps/{id}

Get MCP tool details

POST/v1/mcps/{id}/invoke

Invoke an MCP tool

Providers

GET/v1/providers

List connected providers

POST/v1/providers/{slug}/connect

Initiate provider OAuth

DELETE/v1/providers/{id}

Disconnect a provider

POST/v1/providers/{id}/refresh

Refresh provider credentials

Policies

GET/v1/policies

List policies

GET/v1/policies/{id}

Get policy details

POST/v1/policies/simulate

Simulate policy evaluation

Audit

GET/v1/audit/events

List audit events

GET/v1/audit/events/{id}

Get audit event details

POST/v1/audit/export

Export audit logs

Response Format

All API responses follow a consistent JSON format:

{
  "data": { ... },           // Response data
  "governance": {            // Governance metadata (for MCP invocations)
    "decision": "allow",
    "policy": "policy-name",
    "dlp_result": "passed",
    "audit_event_id": "evt_xxxxx"
  },
  "meta": {                  // Pagination and request metadata
    "request_id": "req_xxxxx",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}
json

Error Handling

Errors return appropriate HTTP status codes with a JSON error body:

{
  "error": {
    "code": "policy_denied",
    "message": "Request denied by policy: block-production-writes",
    "details": {
      "policy": "block-production-writes",
      "reason": "Write operations to production are not allowed for this user"
    }
  },
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-01-15T14:32:00Z"
  }
}
json
StatusDescription
400Bad request - invalid input
401Unauthorized - invalid or missing token
403Forbidden - policy denied the request
404Not found - resource does not exist
429Rate limited - too many requests
500Server error - internal error

Rate Limits

API requests are rate limited based on your plan:

PlanRequests/minMCP Invocations/min
Free6010
Pro600100
EnterpriseCustomCustom

Rate limit headers are included in all responses: X-RateLimit-Limit,X-RateLimit-Remaining, X-RateLimit-Reset.

SDKs

Use our official SDKs for a better developer experience:

TypeScript SDK
import { MCPShield } from '@mcpshield/sdk'

const client = new MCPShield()
const repos = await client.mcps.invoke('github:list_repos')
typescript
Python SDK
from mcpshield import MCPShield

client = MCPShield()
repos = client.mcps.invoke("github:list_repos")
python