Installation & Setup

Connect DealSurface to Claude or Codex in about a minute. Nothing to install.

Get your API key

Create one in Settings → API Keys.

Tip

Create a key, then click Connect my assistant. Everything below is pre-filled for you.

Connect your assistant

Claude Desktop

Download extension

Open the downloaded file.
Paste your API key when Claude asks.
Say: List my DealSurface products

Teams or Enterprise? See the connector steps under Advanced setup.

Claude Code

Copy this message and paste it into Claude Code

Replace ds_live_your_key_here with your key first.

Then just ask: List my DealSurface products

Codex

Copy this message and paste it into Codex

Replace ds_live_your_key_here with your key first.

Then just ask: List my DealSurface products

Something else

Paste these into your client's remote MCP server settings.

Server URL

https://dealsurface.com/api/mcp

Authorization header

Authorization: Bearer ds_live_your_key_here

Advanced setup

Manual setup

For setups the messages above do not cover. The hosted endpoint accepts POST only. Use the exact URL: redirects drop the Authorization header, and keys must never go in the URL.

Endpoint

https://dealsurface.com/api/mcp

Claude Desktop

Desktop extension

Download the extension file.
Double-click it, or Settings, Extensions, Advanced settings, Install Extension.
Paste your API key in the "DealSurface API key" field.
Enable the extension. It uses the Node runtime bundled with Claude Desktop.

Download dealsurface-2.13.0.mcpb

Custom connector (Teams and Enterprise)

Open Settings, Connectors, Add custom connector.
Name: DealSurface. Paste the URL below.
Set Authentication to "No sign-in".
Under "Request headers", add the header below.
Save, then enable the connector in a new chat.

Name

DealSurface

Remote MCP server URL

https://dealsurface.com/api/mcp

Header name

authorization

Header value

Bearer ds_live_your_key_here

The "Request headers" option for custom connectors is rolling out per organization. If you do not see it, use the extension.
Extension SHA-256: ab580a6dfec13b62bd40a456f138ac76e89973ef1c9b75b2014575c949da7cb2
On Team and Enterprise plans an Owner adds the connector once for the whole workspace.
claude_desktop_config.json does not support remote servers, so it is not used here.

Claude Code

Manual setup

Run the command below in your terminal.
Start a new Claude Code session.
Or put the JSON in ~/.claude.json (user scope) or a project .mcp.json.

Add the server

claude mcp add --transport http --scope user dealsurface https://dealsurface.com/api/mcp --header "Authorization: Bearer ds_live_your_key_here"

JSON alternative (~/.claude.json or .mcp.json)

{
  "mcpServers": {
    "dealsurface": {
      "type": "http",
      "url": "https://dealsurface.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ds_live_your_key_here"
      }
    }
  }
}

An .mcp.json in a repository is shared with everyone who clones it. Keep real keys in user scope.

Codex

Manual setup

Append the block below to ~/.codex/config.toml. `codex mcp add` cannot set headers.
Codex asks for approval to edit the file, because it is outside the workspace.
Restart Codex after saving.
Desktop app instead: Settings, MCP servers, Add server, Streamable HTTP. Use the URL and header value below.

config.toml (~/.codex/config.toml)

[mcp_servers.dealsurface]
url = "https://dealsurface.com/api/mcp"
http_headers = { Authorization = "Bearer ds_live_your_key_here" }

Desktop app: URL

https://dealsurface.com/api/mcp

Desktop app: header value

Bearer ds_live_your_key_here

Something else

Streamable HTTP (hosted)

Create a remote or HTTP MCP server in your client.
Use the URL exactly. No redirects, no query parameters, never the key in the URL.
Send the key as an Authorization: Bearer header.
The endpoint accepts POST only.

URL

https://dealsurface.com/api/mcp

Authorization header

Authorization: Bearer ds_live_your_key_here

Generic JSON shape

{
  "name": "dealsurface",
  "transport": "streamable-http",
  "url": "https://dealsurface.com/api/mcp",
  "headers": {
    "Authorization": "Bearer ds_live_your_key_here"
  }
}

The copy-and-paste messages contain your API key, which is sent to your assistant's provider. Use manual setup if that is not acceptable. Deactivate the key any time.

Run locally with npx

Runs over stdio. Needs Node.js 20+.

Claude Desktop config file

Add to claude_desktop_config.json (Settings → Developer → Edit Config), then restart.

claude_desktop_config.json

{
    "mcpServers": {
      "dealsurface": {
        "command": "npx",
        "args": ["-y", "@dealsurface/mcp-server"],
        "env": {
          "DEALSURFACE_API_KEY": "ds_live_your_key_here"
        }
      }
    }
  }

Claude Code

export DEALSURFACE_API_KEY="ds_live_your_key_here"
  claude mcp add dealsurface -- npx @dealsurface/mcp-server

Generic stdio client

{
  "name": "dealsurface",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@dealsurface/mcp-server"],
  "env": {
    "DEALSURFACE_API_KEY": "ds_live_your_key_here"
  }
}

Environment variables

Variable	Required	Description
`DEALSURFACE_API_KEY`	Yes	Your DealSurface API key (starts with `ds_live_`).
`DEALSURFACE_API_URL`	No	Base site URL the server calls (defaults to `https://dealsurface.com`; the server appends `/api/v2`). Only set this if you have been directed to a different environment.

Keep your API key secure

Treat the key like a password. Do not commit it to version control, and deactivate it in Settings → API Keys if it is ever exposed.

Troubleshooting

401 Unauthorized. The key is inactive, expired, mistyped, or lacks the scope the tool needs (read for read tools, outreach for DealMap and outreach tools). Check the key in Settings → API Keys, or create a new one.
“Request headers” is missing in Claude Desktop. That option is rolling out per organization. Use the desktop extension instead.
Codex does not show the tools. Restart Codex or start a new session after editing ~/.codex/config.toml.
Never put the key in the URL. Keys in query strings are rejected. Always send them in the Authorization header.
Use the exact URL. Redirects drop the Authorization header, so register https://dealsurface.com/api/mcp exactly, with no trailing slash, a different host, or http://.

Package links

Overview Tool Catalog