Authentication

The Semaphor MCP server supports two authentication methods. Which one to use depends on your integration pattern.

Project Tokens (Embedded)

For: SaaS applications, AI agents, scripts, and automation.

Generate a project token server-side and pass it as a Bearer token. The token fixes the scope to a single project.

Generate a Token via the UI

The quickest way to get a token for testing:

1. Go to the Projects page in Semaphor
2. Click the Embed button on your project row
3. Navigate to the Generate Token tab
4. Click Show on "Generate a sample project token"
5. Set the expiry duration and click Generate Token
6. Click Copy Token

Generate a Token via API

For production use, generate tokens programmatically from your backend:

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "p_1234567890abcdef",
    "projectSecret": "ps_abcdef1234567890",
    "orgUserId": "user_123",
    "tokenExpiry": 3600
  }'

Pass the Token

Include the token in the Authorization header:

Authorization: Bearer <your_project_token>

MCP clients handle this automatically once configured. See Embedded Quick Start for setup steps.

Supported user types: Organization users and tenant users. See Token API for all token options including tenant configuration, security policies, and semantic domain access.

OAuth (Interactive)

For: End users connecting Claude, Cursor, or other MCP clients.

OAuth uses Kinde as the identity provider. Most MCP clients handle the OAuth flow automatically — you just sign in when prompted.

OAuth Configuration

For client developers or custom integrations, here are the OAuth parameters:

Supported user types: Organization users only (v1).

Security Best Practices

• Store tokens securely — Use environment variables or secret managers, never hard-code tokens in source code
• Rotate tokens — Generate fresh tokens periodically rather than using long-lived ones
• Use HTTPS — Required in production; all MCP communication should be encrypted
• Limit domain access — Use semanticDomainAccess in your project token to restrict which semantic domains are visible to the AI agent
• Apply security policies — Configure CLS, SLS, and RLS policies to control data access at the connection, schema, and row level

See Security for details on how security policies apply to MCP queries.