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

# Developer MCP

> Connect the Firmable developer MCP server to Claude, Cursor, Codex and other AI agents

The developer MCP server lets your AI agent look up companies and people, reveal work emails and
phone numbers, and search Firmable data. Calls use your organisation's
[developer credits](https://docs.firmable.com/developer/credits.md).

| Setting | Value |
| - | - |
| MCP URL | `https://agents.firmable.com/developer/mcp` |
| Transport | Streamable HTTP |
| OAuth client ID | Shown on the portal's **Home** page with **OAuth** selected. Replace `<CLIENT_ID>` below with it. |
| OAuth callback port | `53612` |

> [!NOTE]
>
> The portal's **Home** page shows these steps for the agent you pick, with your client ID or API key
> already filled in. Use that if you can.

## OAuth or API key

* **OAuth**: your agent opens a browser the first time it connects and you sign in to Firmable. Use
  this on your own machine.
* **API key**: your agent sends a [developer API key](https://docs.firmable.com/developer/api-keys.md) with every request. Use
  this for agents that run without a browser, such as on a server or in CI. Replace
  `<YOUR_FIRMABLE_API_KEY>` below with your key.

> [!WARNING]
>
> Firmable only accepts OAuth sign-ins that come back to `http://localhost:53612/oauth/callback`, and
> agents can't register themselves. Always use the client ID and port `53612` exactly as shown. Some
> agents (Codex, Gemini CLI, Windsurf and opencode) pick a different port for their own sign-in, so
> their OAuth setup uses [mcp-remote](https://www.npmjs.com/package/mcp-remote), which needs
> Node.js.

## Let your agent set itself up

Paste this into an agent that can run commands, and it reads the steps and installs Firmable itself:

```text theme={null}
Set up Firmable MCP – https://agents.firmable.com/developer/setup.txt
```

## Claude.ai or Claude Desktop

> [tab] OAuth
>
> 1. In Claude, open **Settings**, then **Connectors**.
> 2. Select **Add custom connector**, name it `Firmable` and paste the MCP URL.
> 3. Under **Advanced settings**, enter the **OAuth Client ID** and leave the client secret blank.
> 4. Select **Add**, then **Connect**, and sign in to Firmable.

> [tab] API key
>
> 1. In Claude, open **Settings**, then **Connectors**.
> 2. Select **Add custom connector**, name it `Firmable` and paste the MCP URL.
> 3. Choose no sign-in, and add a request header named `Authorization` with the value
>    `Bearer <YOUR_FIRMABLE_API_KEY>`.
> 4. Select **Add**.

## ChatGPT

ChatGPT connects with OAuth only.

1. In ChatGPT, open **Settings**, then **Apps**, then **Advanced settings**, and turn on
   **Developer mode**.
2. Select **Create app**, name it `Firmable`, paste the MCP URL and choose **OAuth**.
3. Expand **Advanced OAuth settings**, set **Registration method** to **User-Defined OAuth Client**,
   enter the **Client ID** and leave the secret blank.
4. Select **Create**, sign in to Firmable and select **Allow**.

## Claude Code

> [tab] OAuth
>
> Run in your terminal:
>
> ```bash theme={null}
> claude mcp add --transport http --client-id <CLIENT_ID> --callback-port 53612 firmable https://agents.firmable.com/developer/mcp
> ```

> [tab] API key
>
> Run in your terminal:
>
> ```bash theme={null}
> claude mcp add --transport http firmable https://agents.firmable.com/developer/mcp --header "Authorization: Bearer <YOUR_FIRMABLE_API_KEY>"
> ```

## Cursor

> [tab] OAuth
>
> Add to `~/.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "firmable": {
>       "url": "https://agents.firmable.com/developer/mcp",
>       "auth": {
>         "CLIENT_ID": "<CLIENT_ID>"
>       }
>     }
>   }
> }
> ```

> [tab] API key
>
> Add to `~/.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "firmable": {
>       "url": "https://agents.firmable.com/developer/mcp",
>       "headers": {
>         "Authorization": "Bearer <YOUR_FIRMABLE_API_KEY>"
>       }
>     }
>   }
> }
> ```

## VS Code

> [tab] OAuth
>
> Add to `.vscode/mcp.json`:
>
> ```json theme={null}
> {
>   "servers": {
>     "firmable": {
>       "type": "http",
>       "url": "https://agents.firmable.com/developer/mcp",
>       "oauth": {
>         "clientId": "<CLIENT_ID>"
>       }
>     }
>   }
> }
> ```

> [tab] API key
>
> Add to `.vscode/mcp.json`:
>
> ```json theme={null}
> {
>   "servers": {
>     "firmable": {
>       "type": "http",
>       "url": "https://agents.firmable.com/developer/mcp",
>       "headers": {
>         "Authorization": "Bearer <YOUR_FIRMABLE_API_KEY>"
>       }
>     }
>   }
> }
> ```

## Codex

> [tab] OAuth
>
> Run in your terminal:
>
> ```bash theme={null}
> codex mcp add firmable -- npx -y mcp-remote https://agents.firmable.com/developer/mcp 53612 --host localhost --static-oauth-client-info '{"client_id":"<CLIENT_ID>"}'
> ```

> [tab] API key
>
> Run in your terminal:
>
> ```bash theme={null}
> export FIRMABLE_API_KEY="<YOUR_FIRMABLE_API_KEY>"
> codex mcp add firmable --url https://agents.firmable.com/developer/mcp --bearer-token-env-var FIRMABLE_API_KEY
> ```

## Windsurf

> [tab] OAuth
>
> Add to `~/.codeium/windsurf/mcp_config.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "firmable": {
>       "command": "npx",
>       "args": [
>         "-y",
>         "mcp-remote",
>         "https://agents.firmable.com/developer/mcp",
>         "53612",
>         "--host",
>         "localhost",
>         "--static-oauth-client-info",
>         "{\"client_id\":\"<CLIENT_ID>\"}"
>       ]
>     }
>   }
> }
> ```

> [tab] API key
>
> Add to `~/.codeium/windsurf/mcp_config.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "firmable": {
>       "serverUrl": "https://agents.firmable.com/developer/mcp",
>       "headers": {
>         "Authorization": "Bearer <YOUR_FIRMABLE_API_KEY>"
>       }
>     }
>   }
> }
> ```

## Gemini CLI

> [tab] OAuth
>
> Add to `~/.gemini/settings.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "firmable": {
>       "command": "npx",
>       "args": [
>         "-y",
>         "mcp-remote",
>         "https://agents.firmable.com/developer/mcp",
>         "53612",
>         "--host",
>         "localhost",
>         "--static-oauth-client-info",
>         "{\"client_id\":\"<CLIENT_ID>\"}"
>       ]
>     }
>   }
> }
> ```

> [tab] API key
>
> Run in your terminal:
>
> ```bash theme={null}
> gemini mcp add --transport http firmable https://agents.firmable.com/developer/mcp --header "Authorization: Bearer <YOUR_FIRMABLE_API_KEY>"
> ```

## opencode

> [tab] OAuth
>
> Add to `opencode.json`:
>
> ```json theme={null}
> {
>   "$schema": "https://opencode.ai/config.json",
>   "mcp": {
>     "firmable": {
>       "type": "local",
>       "command": [
>         "npx",
>         "-y",
>         "mcp-remote",
>         "https://agents.firmable.com/developer/mcp",
>         "53612",
>         "--host",
>         "localhost",
>         "--static-oauth-client-info",
>         "{\"client_id\":\"<CLIENT_ID>\"}"
>       ],
>       "enabled": true
>     }
>   }
> }
> ```

> [tab] API key
>
> Add to `opencode.json`:
>
> ```json theme={null}
> {
>   "$schema": "https://opencode.ai/config.json",
>   "mcp": {
>     "firmable": {
>       "type": "remote",
>       "url": "https://agents.firmable.com/developer/mcp",
>       "enabled": true,
>       "headers": {
>         "Authorization": "Bearer <YOUR_FIRMABLE_API_KEY>"
>       }
>     }
>   }
> }
> ```

## Other MCP clients

> [tab] OAuth
>
> Add to `mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "firmable": {
>       "type": "http",
>       "url": "https://agents.firmable.com/developer/mcp",
>       "oauth": {
>         "clientId": "<CLIENT_ID>"
>       }
>     }
>   }
> }
> ```

> [tab] API key
>
> Add to `mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "firmable": {
>       "type": "http",
>       "url": "https://agents.firmable.com/developer/mcp",
>       "headers": {
>         "Authorization": "Bearer <YOUR_FIRMABLE_API_KEY>"
>       }
>     }
>   }
> }
> ```

## Check it works

Ask your agent: *"Use Firmable to look up the company at firmable.com."* If it can't find the Firmable
tools, restart the agent. If sign-in fails, check you used the client ID and port `53612` exactly
as shown.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.