> ## Documentation Index
> Fetch the complete documentation index at: https://developer.firstsales.io/llms.txt
> Use this file to discover all available pages before exploring further.

# FirstSales MCP server

> Connect an AI client to FirstSales through the product MCP endpoint.

The product MCP endpoint is:

```text theme={null}
https://api.app.firstsales.io/mcp
```

FirstSales uses the MCP Streamable HTTP transport and the stable `2025-11-25`
protocol revision. Clients must send JSON-RPC messages with `POST` and include both
`application/json` and `text/event-stream` in `Accept`.

## Authorization

The endpoint is an OAuth-protected resource. A client must obtain an access token for
the canonical resource URI and send it as a bearer token:

```http theme={null}
Authorization: Bearer <access-token>
MCP-Protocol-Version: 2025-11-25
```

OAuth Protected Resource Metadata is discoverable at:

```text theme={null}
https://api.app.firstsales.io/.well-known/oauth-protected-resource/mcp
```

The authorization server is FirstSales at `https://app.firstsales.io`. Its public
OAuth metadata and endpoints are:

```text theme={null}
https://app.firstsales.io/.well-known/oauth-authorization-server
https://app.firstsales.io/api/auth/oauth2/register
https://app.firstsales.io/api/auth/oauth2/authorize
https://app.firstsales.io/api/auth/oauth2/token
https://app.firstsales.io/api/auth/jwks
```

MCP clients should use dynamic public-client registration with PKCE (`S256`). If
the user is not signed in, FirstSales sends them through the normal login flow
first. The consent flow then shows every organization and accessible workspace;
the user must explicitly choose the workspace boundary before approving access.
The resulting token carries only those tenant grants.

The token must satisfy the configured issuer, audience/resource, expiry, and scope and
must carry the delegated capability required by the requested tool. Dashboard session
cookies and Developer API keys are not accepted by product MCP.

## Release status

The endpoint is release-gated. Until the product OAuth/delegation authority is
configured and a capability is explicitly closed/released for MCP, requests fail
closed or expose no tools. OAuth registration and tenant consent do not by
themselves release an API action. This prevents a partially configured server from
becoming an unauthenticated data or action surface.

## Production activation checklist

The backend starts this route disabled unless all of these deployment values are
present and valid:

```text theme={null}
MCP_ENABLED=true
MCP_RESOURCE_URL=https://api.app.firstsales.io/mcp
MCP_OAUTH_ISSUER=<your OAuth issuer>
MCP_OAUTH_AUDIENCE=https://api.app.firstsales.io/mcp
MCP_OAUTH_JWKS_URL=<your issuer JWKS URL>
MCP_ALLOWED_ORIGINS=<approved client origins>
MCP_REQUIRED_SCOPES=mcp:access
```

Configuration alone does not release tools. A capability must also be marked
`closed` or `released` for MCP in the canonical capability ledger, have a
manifest-bound tenant/delegation grant, and have an explicit first-party handler
binding. Until all three conditions hold, `tools/list` remains empty.

## Protocol behavior

* `initialize`, `ping`, `tools/list`, `resources/list`, and `prompts/list` use JSON-RPC.
* Notifications return `202 Accepted` without a response body.
* Invalid `Origin`, protocol, media type, or authorization values fail closed.
* Tool execution errors are returned as MCP tool results with `isError: true` so an
  agent can recover without treating a business error as a transport failure.