Skip to Content

Security

Security model and controls in ISA MCP.

Security Layers

  • Authentication: JWT and API key support
  • Authorization: tool-level security levels (LOW, MEDIUM, HIGH)
  • Tenant isolation: org-scoped data filtering
  • Input protection: shell, file path, and network request hardening
  • Auditability: security event logging and authorization traces

Authentication

JWT

Use bearer tokens with organization context:

Authorization: Bearer <jwt_token>
X-Organization-Id: <org_id>

Expected context includes user_id, organization_id, and authorized_orgs.

API Keys

Use API keys in headers:

X-API-Key: <api_key>

API key verification is integrated with the auth stack. Requests that include API keys in query parameters such as ?api_key=... are rejected with HTTP 400 to avoid leaking credentials via browser history, proxy logs, and referrer headers.

Tool Security Levels

LevelTypical RiskAuthorization
LOWRead-only or safe operationsNot required
MEDIUMControlled writes / trusted external callsNot required
HIGHShell, filesystem writes, sensitive network operationsRequired

HIGH tools trigger explicit authorization flow before execution.

Hardening Areas

Shell Execution

  • dangerous command patterns are blocked
  • high-risk operations require authorization
  • execution is logged for audit and traceability

File Operations

  • path traversal checks with resolved paths
  • sensitive system paths blocked by policy
  • destructive operations gated by authorization

External Fetch / SSRF Controls

  • allowlisted registry hosts
  • private and metadata IP ranges blocked
  • restrictive scheme handling and redirect controls

OAuth 2.0 Resource Server (RFC 8707)

MCP acts as an OAuth 2.0 resource server, accepting Bearer tokens issued by the isA Authorization Server. This enables external applications to call MCP tools on behalf of a user using delegated authorization.

Bearer Token Validation

Include the access token on every request:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-Organization-Id: org_abc123

MCP validates Bearer tokens using RS256 or ES256 signature verification. Tokens must include the appropriate mcp:* scope for the operation being requested.

Resource Server Metadata

Discover the resource server configuration automatically:

curl https://mcp.isa.ai/.well-known/oauth-protected-resource
{
  "resource": "https://mcp.isa.ai",
  "authorization_servers": ["https://auth.isa.ai"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": [
    "mcp:tools:execute",
    "mcp:tools:read",
    "mcp:resources:read",
    "mcp:resources:write",
    "mcp:admin:servers",
    "mcp:admin:tenants"
  ]
}

This endpoint is public (no auth required) and follows RFC 8707 Protected Resource Metadata.

Scope Requirements

OperationRequired scope
Execute a toolmcp:tools:execute
List tools / read schemasmcp:tools:read
Read MCP resourcesmcp:resources:read
Write MCP resourcesmcp:resources:write
Manage MCP serversmcp:admin:servers
Multi-tenant adminmcp:admin:tenants

Scope Migration

Scopes changed from a2a.* to mcp:* in v0.7. The auth middleware auto-normalizes legacy a2a.* scopes during the transition window. See the scope migration guide for details.

Browser POST Tools

Tools that use POST from browser contexts (via Server-Sent Events) are supported with Bearer token auth. The auth middleware handles CORS pre-flight and token validation for browser-originated requests.

Security Response Headers

Authentication and authorization failures use standard headers:

  • 401 responses include WWW-Authenticate
  • 403 insufficient-scope responses include WWW-Authenticate with the required scope

Rate-limited requests also include standard backoff headers when the limiter has enough metadata:

  • Retry-After
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

Rate Limit Flow

When a tool is throttled, the structured error metadata is propagated to the HTTP layer:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000

Clients should respect Retry-After instead of retrying immediately.

Home