Reference

MCP Setup

SaaSignal exposes a production Model Context Protocol (MCP) endpoint. AI agents like Claude, Cursor, Windsurf, and others can connect to it and call documented HTTP routes directly through MCP by OpenAPI operationId when the active credential has the required auth context and scopes, plus a small set of legacy operational aliases.

Best first step for agents: after connecting, call saasignal_surface_map or saasignal_skill, or read GET /skills/saasignal. Those discovery tools explain the difference between tools/list (what this credential can call now) and the broader SaaSignal catalog in /skills/saasignal, /llms.txt, and /api/openapi.json.

Add to your MCP config

If your MCP client supports browser authorization, use this headerless config first. The client will discover SaaSignal's protected-resource metadata, open the browser to saasignal.saastemly.com, and let you approve access with your existing dashboard login.

.mcp.json

{
  "mcpServers": {
    "saasignal": {
      "type": "http",
      "url": "https://api.saasignal.saastemly.com/mcp"
    }
  }
}

Browser OAuth is the primary path: OAuth-capable clients receive a user-level JWT access token that grants access across all your organizations. Tools are filtered during tools/list based on the scopes you approved, and unsupported tool calls return a proper OAuth insufficient_scope challenge.

Manual fallback: API key headers

If your MCP client does not support browser authorization yet, you can keep using a project API key:

.mcp.json

{
  "mcpServers": {
    "saasignal": {
      "type": "http",
      "url": "https://api.saasignal.saastemly.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}

You can create an API key in four ways:

Dashboard — go to Dashboard → select a project → Tokens → Create Token, pick your scopes, and copy the sk_live_... secret.
MCP — if your current MCP session can see createToken in tools/list, call it directly through MCP with the desired scopes and optional project_id.
REST API — POST /core/organizations/:org_id/tokens with project_id in the body. See Tokens.
TypeScript SDK — use ss.core.orgs.createToken({ ... }) from the saasignal npm package.

Available tools

When connected, the agent gets access to MCP tools generated from documented HTTP routes by OpenAPI operationId, along with the long-lived legacy aliases used by older prompts and integrations. If a documented route is visible in tools/list, the agent can call it directly through MCP without dropping to REST.

Automatic route exposure: if you add a new Hono route with describeRoute(...) metadata and a stable operationId, it becomes available through MCP automatically after deploy. tools/list is the live source of truth for the current credential and scope set, while /skills/saasignal, /llms.txt, and /api/openapi.json describe the broader platform, including scope-gated routes that might not be visible in the current session.

Tool

Scope required

saasignal_skill, saasignal_surface_map

none

listProjects, storageListBuckets, logisticsGeoCreate, and the rest of the documented HTTP surface

Matches each route's documented scope

kv_get, channel_publish, job_create, and other legacy aliases

Same scopes as their underlying primitives

Practical note: generated MCP route tools proxy the real HTTP handlers, so request validation, auth, billing, and side effects stay aligned with REST. For large binary uploads or long-lived streams, direct REST or the SDK may still be a more ergonomic choice.

Immediate discovery examples

If an agent needs proof that control-plane, search, and delivery routes are MCP-callable, these are good first checks:

createToken and createBrowserToken for scoped access-token flows.
searchCreateIndex and searchQueryIndex for managed retrieval and search.
deliveryOrderCreate, deliveryDriverList, and deliveryDispatchSuggest for delivery module orchestration.

Example prompts: "Create a scoped access token for project proj_123 with kv:read only", "Query the support-docs search index for refund policy hits", or "Suggest the best nearby drivers for order ord_123".

If a tool is missing: compare tools/list with /skills/saasignal or /api/openapi.json. A missing route usually means the credential lacks the required scope or project context. Reconnect with the right scopes, or expect the next call to fail with WWW-Authenticate: Bearer error="insufficient_scope" and the required scope list.

Editor-specific setup

Claude Code

Create a .mcp.json file in your project root (or ~/.claude/.mcp.json for global access):

.mcp.json

{
  "mcpServers": {
    "saasignal": {
      "type": "http",
      "url": "https://api.saasignal.saastemly.com/mcp"
    }
  }
}

If your build of Claude Code does not support browser authorization yet, use the manual API-key fallback from the section above.

Cursor

Go to Settings → MCP Servers → Add Server, then add the SaaSignal MCP URL. Cursor should open the browser for authorization automatically:

cursor mcp config

Name: saasignal
Type: http
URL: https://api.saasignal.saastemly.com/mcp

Any MCP-compatible client

The MCP endpoint supports the Streamable HTTP transport. Browser-OAuth-capable clients can use the bare URL; manual clients can add an API key header:

endpoint

POST https://api.saasignal.saastemly.com/mcp
Content-Type: application/json

Test it: After adding the MCP config, connect the server in your editor and approve the browser prompt. Then ask your AI agent: "Call saasignal_surface_map and summarize the full SaaSignal platform", "Use listProjects to show my org's projects", or "List the live MCP tools and call storageListBuckets". The agent will use the SaaSignal tools automatically.