Docs/MCP Authentication

MCP Authentication

Agentic

Secure machine-to-machine communication between AI agents and MCP servers. Agents obtain JWT tokens via client_credentials, MCP servers verify locally using JWKS — no per-request calls to Astapa.

1The flow

Astapa acts as the Identity Provider for the MCP ecosystem. Three steps, zero session management:

flow.txttext

Agent → Astapa    POST /api/platform/token (client_credentials)  → JWT
Agent → MCP Server  Authorization: Bearer <JWT>
MCP Server → verify locally (JWKS cache) → extract claims → allow/deny

Stateless

No sessions, no cookies. Just a JWT in the Authorization header.

Local verification

MCP servers verify tokens using cached JWKS keys — no network calls.

Plan-gated

Scopes are derived from the project's plan tier. Upgrade plan = more scopes.

2Get a token (agent side)

Call the token endpoint with your project's credentials:

get-token.tstypescript

const res = await fetch("https://astapa.com/api/platform/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: "proj_xxx",
    client_secret: "your_secret",
  }),
});

const { access_token, token_type, expires_in } = await res.json();
// access_token: JWT string
// token_type: "Bearer"
// expires_in: 3600 (seconds)

No refresh tokens for M2M

Client credentials grants don't issue refresh tokens. When the token expires, request a new one. Tokens last 1 hour by default.

3JWT claims

The issued JWT contains these claims:

Claim	Description
`iss`	Issuer — always `auth.astapa.com`
`sub`	Subject — the project's client_id
`org_id`	Organization / builder ID
`aud`	Audience — the project's client_id
`scopes`	Granted scopes (e.g. `tool:read`, `tool:write`)
`plan`	Subscription tier: free, pro, or enterprise
`exp`	Expiration timestamp (Unix seconds)
`environment`	`production` or `sandbox`

4Scopes by plan

Scopes are automatically derived from the project's plan tier:

Plan	Scopes granted
free	`tool:read`
pro	`tool:read` `tool:write`
enterprise	`tool:read` `tool:write` `tool:admin`

5JWKS endpoint

The public key for verifying JWTs is available at:

jwks.txthttp

GET https://auth.astapa.com/.well-known/jwks.json

MCP servers should cache the JWKS response and only refetch when:

The cache TTL expires (recommended: 10 minutes)
A JWT contains a kid not found in the cache (key rotation)

6Security requirements

MCP servers must reject tokens if:

Signature is invalid (RS256 verification fails)
Issuer doesn't match auth.astapa.com
Audience doesn't match this MCP server's identifier
Token is expired

Anti-patterns

Do NOT call Astapa to validate JWT per request
Do NOT store sessions for JWT validation
Do NOT skip signature verification
Do NOT use symmetric keys (HS256) for multi-tenant systems