Auth

Add auth to a generated MCP server

Configure API keys, bearer tokens, and OAuth-style credentials for generated MCP tools without leaking secrets into tool metadata.

Jun 25, 20268 min readIntermediate

Steps

Read the auth section in the source spec

Check whether the OpenAPI document uses securitySchemes for apiKey, http bearer, OAuth2, or per-operation overrides. The generated server should preserve that intent as runtime policy, not prose.

Mark private tools as auth-required

Before attaching secrets, review which routes should require credentials. Public catalog routes can stay visible, but state-changing or account-specific calls should return auth_required until a credential is configured.

Attach a credential outside the prompt path

Credentials belong in the server credential store or environment, not in descriptions, examples, or generated docs. Use a test token first.

Example

curl -sS -X POST https://astrail.dev/api/credentials \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ASTRAIL_API_KEY" \
  -d '{
    "server_id": "SERVER_ID",
    "kind": "bearer",
    "label": "staging token",
    "value": "UPSTREAM_TEST_TOKEN"
  }'

Verify unauthenticated behavior

Call a private tool without credentials and confirm it fails closed. The error should be explicit enough for the agent to recover without revealing the missing secret.

Example

curl -sS -X POST https://astrail.dev/api/mcp/SERVER_ID \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"create_invoice","arguments":{}}}'

Verify authenticated behavior

Once a credential is attached, repeat the call with the Astrail API key required by your private endpoint policy. Inspect logs for credential redaction and upstream status.

Production checks

No secret appears in tools/list, search_docs, generated SDK docs, logs, or error bodies.

Private routes return auth_required or permission_denied without configured credentials.

Credential injection happens server-side at execution time.

Destructive methods are reviewed separately from read-only methods.

FAQ

Can an MCP tool description include an API key?

No. Tool descriptions are prompt-visible metadata. Store credentials separately and inject them only during the runtime call.

Should public MCP endpoints require Astrail auth?

Public metadata can be visible, but private tools and live upstream calls should require the workspace policy your team chooses.