Authentication & security

OAuth and API-key auth, scopes, org isolation, and safe-use guidance

The Signa MCP server supports two authentication methods: API keys and OAuth 2.1. Use whichever fits your setup.

Overview

	API Key	OAuth 2.1
Header	Bearer sig_*	Bearer <jwt_token>
Setup	Paste key into MCP client config	Browser login + consent (automatic)
Best for	Scripts, CI/CD, quick setup	Interactive AI agents (Claude, ChatGPT)
Rate limit	Per org, by tier	Per org, MCP tier (100 req/min)

Using an API key

If you already have a Signa API key, you can use it directly with MCP. No OAuth flow needed.

For Claude Code with an API key header:

claude mcp add signa https://api.signa.so/mcp -t http -h "Authorization: Bearer sig_YOUR_KEY"

For Claude Desktop with a static header:

{
  "mcpServers": {
    "signa": {
      "url": "https://api.signa.so/mcp",
      "type": "streamableHttp",
      "headers": {
        "Authorization": "Bearer sig_YOUR_KEY"
      }
    }
  }
}

Using OAuth

MCP clients that support OAuth will handle the login flow automatically. When you first connect, a browser window opens for you to sign in at app.signa.so and approve access. After that, the token refreshes silently.

Discovery

MCP clients discover the authorization server automatically via a standard endpoint:

curl https://api.signa.so/.well-known/oauth-protected-resource

{
  "resource": "https://api.signa.so/mcp",
  "authorization_servers": ["https://app.signa.so"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["read", "search", "offline_access"]
}

This follows RFC 9728 (OAuth 2.0 Protected Resource Metadata).

Scopes

Scope	Grants access to
read / search / trademarks:read	Read-only tools — search, view, and list trademarks, owners, entities, attorneys, firms, proceedings, watches, alerts, and webhooks. Global reference-data tools (offices, jurisdictions, classifications, rules) aren’t org-scoped but still require trademarks:read.
billing:read	Account & usage tools — get_usage, get_usage_summary, get_account
portfolios:manage	Watch writes and watch-scoped tools — signa_watches_create/update/delete, pause_watch, resume_watch, preview_watch, get_watch_diagnostics, list_alerts_for_watch, lookup_alert
offline_access	Refresh token for long-lived sessions

Most MCP clients request a read scope by default, which covers every read-only tool. Add billing:read if you want your agent to inspect usage and account details, and portfolios:manage only if you want it to create or change watches.

If a tool needs a scope your token lacks, the call returns a 403 with a clear message naming the required scope — the rest of the session keeps working. To keep an agent strictly read-only, issue an API key without portfolios:manage.

Usage & metering

MCP tool calls are metered exactly like REST requests. Each tools/call counts against your plan’s quota and appears in your usage and request logs, classified by the same endpoint type its REST counterpart uses (search, read, monitoring) — so an MCP search costs the same as POST /v1/trademarks. The initialize and tools/list handshake calls are never metered.

• Reference-data tools (offices, jurisdictions, classifications, goods/services, design codes, rules) are logged but not billed — they don’t consume quota.
• Account & usage tools (get_usage, get_usage_summary, get_account) are utility calls — neither billed nor counted against quota.
• Over-quota calls return a clear Quota exceeded error naming the limit that was hit and when it resets, instead of running the tool.

You can check your own consumption at any time with get_usage and get_usage_summary (see Account & usage).

OAuth sessions are metered to the organization selected during login. Request logs and billing events for OAuth MCP calls have no API key ID because no API key is involved.

Token format

Access tokens are JWTs signed by the Signa auth server. They contain:

Claim	Description
sub	Your user ID
org_id	Your organization ID (custom claim)
scope	Granted scopes (space-separated)
aud	https://api.signa.so/mcp
iss	https://app.signa.so/api/auth
exp	Token expiration timestamp

The Signa API validates tokens using the JWKS endpoint at https://app.signa.so/api/auth/jwks.

Consent

On first connection, you will see a consent screen listing the permissions the MCP client is requesting. You can approve or deny access. Approved consents are remembered so you are not prompted again on reconnection.

You can revoke consent at any time from your account settings at app.signa.so.

Security

The MCP server is built so an AI agent can only ever act as you, within your org:

• Org isolation. Org context is resolved from your token or API key on every request — never from a tool argument. An agent cannot read or modify another organization’s data, even if prompted to.
• Least privilege. Scopes are enforced per tool. For read-only use, issue an API key without portfolios:manage so write tools (signa_watches_create/update/delete) are unavailable. Keep separate keys per integration so you can revoke one without affecting others.
• Secrets stay server-side. Webhook signing secrets are never returned through MCP — signa_webhooks_* tools always redact them.
• Review tool calls. MCP clients let you approve tool calls before they run. Keep approval on for any agent with portfolios:manage, and treat tool results as data an untrusted prompt could try to act on (standard prompt-injection hygiene).
• Data residency. Tool results are trademark data scoped to your org, returned to the client you connected. Nothing is shared with other tenants.

Rate limits

MCP requests share a dedicated rate limit tier:

Tier	Limit	Window
MCP	1,000 requests	60 seconds

Rate limit headers are returned on every response:

RateLimit-Policy: 1000;w=60
RateLimit: remaining=987, reset=42

RateLimit-Policy lists every policy in effect as a comma-separated list (plan per-endpoint-type limit first, transport-tier ceiling second), deduplicated to a single entry when the limits coincide — as they do for MCP requests on the beta plan, so a single 1000;w=60 is shown. See Rate Limits for the full header semantics.

If you hit the limit, the response includes a Retry-After header.

Troubleshooting

401: Missing Authorization header

Your MCP client is not sending the access token. Re-authenticate by removing and re-adding the MCP connection.

401: Access token missing org_id claim

Your Signa account has not completed onboarding. Log in at app.signa.so and create an organization first.

401: Invalid or expired access token

Your token has expired. Most MCP clients handle refresh automatically. If the error persists, remove and re-add the connection to re-authenticate.

429: Rate limited

You are sending more than 1,000 MCP requests per minute. Wait for the Retry-After period or reduce request frequency.