GitHubDashboard

Authentication

Learn how to authenticate with MCP Shield and manage tokens for secure API access.

Overview

MCP Shield uses a two-layer authentication model that separates client authentication from provider credentials. This ensures your provider tokens are never exposed to AI clients while still enabling governed access to external services.

MCP Shield Tokens

Tokens you use to authenticate with MCP Shield. These are what your AI clients (Cursor, Claude) use to connect to the gateway.

Provider Credentials

OAuth tokens and API keys for external services (GitHub, Vercel). These are stored securely and never exposed to clients.

Token Types

User Tokens
mcp_live_
Personal tokens tied to your user account

User tokens are ideal for personal development workflows. They inherit your permissions and are scoped to your account.

Personal useDevelopmentTesting
Service Account Tokens
svc_live_
Machine tokens for CI/CD and automation

Service account tokens are not tied to a human user. Use them for CI/CD pipelines, automated workflows, and server-to-server communication.

CI/CDAutomationServer-to-server
Temporary Tokens
tmp_
Short-lived tokens for specific tasks

Temporary tokens expire quickly and are ideal for one-time operations or when you need to grant limited access for a specific task.

Short-livedOne-time tasksLimited scope

Creating Tokens

Via Dashboard

  1. Navigate to Dashboard → Tokens
  2. Click Create Token
  3. Select the token type and configure scopes
  4. Copy the token immediately - it won't be shown again

Via CLI

# Create a new user token
mcp-shield tokens create --name "cursor-dev" --type user

# Create a service account token for CI
mcp-shield tokens create --name "github-actions" --type service \
  --scopes "mcp:invoke:approved,usage:read"

# Create a temporary token (expires in 1 hour)
mcp-shield tokens create --name "quick-task" --type temporary \
  --expires 1h
bash

Using Tokens

Environment Variable

The recommended way to use tokens is via environment variables:

export MCP_SHIELD_TOKEN=mcp_live_xxxxxxxxxxxxxxxx
bash

HTTP Header

Include the token in the Authorization header for API requests:

curl https://gateway.mcpshield.com/v1/mcps \
  -H "Authorization: Bearer mcp_live_xxxxxxxxxxxxxxxx"
bash

MCP Client Configuration

Configure your AI client to use the token:

{
  "mcpServers": {
    "mcp-shield": {
      "url": "https://gateway.mcpshield.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_SHIELD_TOKEN}"
      }
    }
  }
}
json

Token Scopes

Scopes control what actions a token can perform. Follow the principle of least privilege.

ScopeDescription
mcp:invoke:approvedInvoke approved MCPs
mcp:invoke:*Invoke any MCP (admin only)
mcp:listList available MCPs
policy:simulateRun policy simulations
usage:readView usage analytics
audit:readView audit logs

Security Best Practices

Use environment variables

Never hardcode tokens in your code or commit them to version control.

Use minimal scopes

Only request the scopes your application actually needs.

Rotate tokens regularly

Set up a rotation schedule, especially for service account tokens.

Revoke compromised tokens immediately

If a token is exposed, revoke it from the dashboard or CLI right away.

Revoking Tokens

# Revoke a specific token
mcp-shield tokens revoke --id tok_xxxxxxxx

# Revoke all tokens for a service account
mcp-shield tokens revoke --service-account "github-actions"

# List and filter tokens
mcp-shield tokens list --type service --status active
bash

Token Lifecycle

Created→Active→Expiring→Expired/Revoked

Automatic Rotation

Enterprise plans support automatic token rotation with zero-downtime handoff.

Usage Tracking

Every token tracks last used timestamp and IP for security auditing.

Next Steps

MCP Gateway
Learn how to use authenticated tokens with the MCP gateway
CLI Reference
Manage tokens and authentication from the command line