# setup-mcp

Walks through connecting Deepgram's MCP server to your editor or AI coding tool, including a docs option that needs no API key.

Skill by Deepgram. Category: Agent craft.

## Install

Project (for this project only):

```sh
npx skills add deepgram/skills --skill setup-mcp
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add deepgram/skills --skill setup-mcp -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass
- ZeroLeaks: Pass

Installs: 336. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/deepgram/skills/setup-mcp)

## Source

[Open the source](https://github.com/deepgram/skills/tree/HEAD/skills/setup-mcp). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: setup-mcp
description: >
  Set up a Deepgram MCP server for your AI coding tool. Offers three paths: the Deepgram CLI
  MCP proxy (dg mcp), the standalone deepgram-mcp package, and the credential-free hosted
  documentation MCP. Use whenever someone wants to install Deepgram's agentic tools, set up
  the MCP server, or connect their editor to Deepgram.
---

# Install a Deepgram MCP Server

You are setting up Deepgram MCP integration for the user. Follow these steps.

## Step 1: Pick a path

Three paths exist. Pick by whether the user has, or wants, a Deepgram API key.

| Path | Server | Credentials | Install footprint |
|---|---|---|---|
| **A** | Deepgram CLI MCP proxy (`dg mcp`) | Deepgram API key **required** | Full CLI (`deepctl`) |
| **B** | Standalone `deepgram-mcp` | Deepgram API key **required** | One Python package |
| **C** | Hosted docs MCP (`/_mcp/server`) | **None** | Nothing to install |

Decision rule:

- The user already has the CLI, or wants `dg listen` / `dg speak` / `dg init` too → **Path A**.
- The user has an API key but wants only the MCP server, no CLI → **Path B**.
- The user has no API key, or wants something working in one command → **Path C**.

A key-authenticated hosted variant of Paths A/B also exists at `api.dx.deepgram.com/kapa/mcp`,
with nothing to install — see "The kapa endpoints are not credential-free" below.

Paths A and B are the same server: `dg mcp` wraps the `deepgram-mcp` package. Both proxy
Deepgram's developer API and fetch their tool list from Deepgram at runtime, so new tools
appear on reconnect without a package upgrade. As of this writing that list is a single
documentation and knowledge-source search tool (`search_deepgram_knowledge_sources`) — check
`tools/list` in the user's client for what is live rather than promising a tool set.

Paths A/B and Path C both answer Deepgram questions from documentation, so installing more
than one is usually redundant. Path C is the only one that works with no credentials.

## Step 2: Detect the environment

Determine which AI coding tool the user is running. Check for:

- **Claude Code** — look for a `.claude/` directory in the project or user home
- **Cursor** — look for a `.cursor/` directory in the project root
- **Windsurf** — look for a `.windsurf/` directory in the project root

If multiple are detected, or none are detected, ask the user which tool they want to configure.

## Step 3: Ask about scope

Ask the user whether they want the MCP server configured:

- **For this project only** (recommended for team repos)
- **Globally** (available in all projects)

---

## Path A — Deepgram CLI MCP proxy (`dg mcp`)

### A1. Install the CLI

Check first: `dg --version` (or `deepctl --version`, or `where dg` on Windows). The package is
`deepctl` and installs three interchangeable binaries — `dg`, `deepctl`, and `deepgram`.

```sh
# macOS / Linux — Homebrew (also brings in ffmpeg and portaudio)
brew install deepgram/tap/deepgram

# macOS / Linux — install script
curl -fsSL https://deepgram.com/install.sh | sh

# pip / uv / pipx
pip install deepctl
uv tool install deepctl
pipx install deepctl
```

```powershell
# Windows — PowerShell
iwr https://deepgram.com/install.ps1 -useb | iex
```

To upgrade, use the installer that put it there: `pip install -U deepctl`,
`uv tool upgrade deepctl`, `pipx upgrade deepctl`, `brew upgrade deepgram`, or re-run the install
script. `dg update --check-only` reports whether a newer release exists; on a pip install, bare
`dg update` reports `installation_method: null` instead of upgrading.

The fully qualified Homebrew name matters: Homebrew 6 loads a third-party formula only after it
is trusted, and `brew install deepgram/tap/deepgram` trusts that one formula, where
`brew tap deepgram/tap && brew install deepgram` fails until a separate `brew trust` step. The
tap formula pins `deepctl-0.2.26`; pip, uv, and pipx install 0.3.1.

### A2. Authenticate — required

`dg mcp` will not start without credentials. Do this before configuring any editor:

```sh
dg login                  # interactive; or dg login --api-key <KEY>
dg whoami                 # confirm: "authenticated": true
```

`DEEPGRAM_API_KEY` in the environment works instead of `dg login`. Get a key at
<https://console.deepgram.com>.

### A3. Configure the editor

#### Claude Code

```sh
# Project scope
claude mcp add deepgram --scope project dg mcp

# User/global scope
claude mcp add deepgram dg mcp
```

#### Cursor

Write or merge into the project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "deepgram": {
      "type": "stdio",
      "command": "dg",
      "args": ["mcp"]
    }
  }
}
```

#### Windsurf

Write or merge into the project's `.windsurf/mcp.json`, using the same object as Cursor above.

#### Without a permanent install

`uvx` and `pipx run` fetch `deepctl` on demand. Credentials still come from `dg login` or
`DEEPGRAM_API_KEY`:

```json
{
  "mcpServers": {
    "deepgram": {
      "command": "uvx",
      "args": ["deepctl", "mcp"]
    }
  }
}
```

#### Other tools

- **Transport:** stdio
- **Command:** `dg`
- **Args:** `["mcp"]`

`dg mcp --transport sse --port 8000` serves SSE instead, for clients that need HTTP.

---

## Path B — Standalone `deepgram-mcp`

The MCP server without the rest of the CLI. One package, one binary.

```sh
pip install deepgram-mcp
export DEEPGRAM_API_KEY=your_key_here
```

`deepgram-mcp` is a PyPI package. The npm package of the same name is unrelated third-party code
that also asks for `DEEPGRAM_API_KEY`, so do not run `npx deepgram-mcp`.

#### Claude Code

```sh
claude mcp add deepgram -- deepgram-mcp
```

#### Cursor / Windsurf

Write or merge into `.cursor/mcp.json` or the Windsurf MCP config:

```json
{
  "mcpServers": {
    "deepgram": {
      "command": "deepgram-mcp",
      "env": {
        "DEEPGRAM_API_KEY": "your_key_here"
      }
    }
  }
}
```

`--api-key` overrides the environment variable, and `--transport sse --port 8000` serves SSE.
Source: <https://github.com/deepgram/mcp>.

---

## Path C — Hosted documentation MCP (no credentials)

Use `https://developers.deepgram.com/_mcp/server`. It answers unauthenticated, needs no API
key, and exposes one tool, `searchDocs`, which returns documentation passages with source URLs.

It is not a plain liveness URL. `HEAD` returns 404, a `GET` with the MCP
`Accept: application/json, text/event-stream` header returns 405, and a bare `GET` returns a
JSON descriptor of the server rather than an MCP response. Only a `POST` `initialize` exercises
the server; it answers 200 with `serverInfo.name` `fern-docs-mcp-server`:

```sh
curl -s -X POST https://developers.deepgram.com/_mcp/server \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'
```

#### Claude Code

```sh
# Project scope
claude mcp add deepgram-docs --scope project --transport http https://developers.deepgram.com/_mcp/server

# User/global scope
claude mcp add deepgram-docs --transport http https://developers.deepgram.com/_mcp/server
```

#### Cursor

Write or merge into the project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "deepgram-docs": {
      "type": "http",
      "url": "https://developers.deepgram.com/_mcp/server"
    }
  }
}
```

#### Windsurf

Write or merge into the project's `.windsurf/mcp.json`, using the same object as Cursor above.

#### Other tools

- **Type:** HTTP
- **URL:** `https://developers.deepgram.com/_mcp/server`

### The kapa endpoints are not credential-free

`https://api.dx.deepgram.com/kapa/mcp` and `https://deepgram.mcp.kapa.ai` both exist, and both
reject an unauthenticated request with HTTP 401 plus a `WWW-Authenticate: Bearer
resource_metadata=...` header, so a client that implements MCP's OAuth flow can connect to either.
They differ in whether a Deepgram API key works:

- **`api.dx.deepgram.com/kapa/mcp` accepts a Deepgram API key.** Send it as either
  `Authorization: Token <KEY>` or `Authorization: Bearer <KEY>` and `initialize` returns 200 from
  `deepgram-mcp-relay`; an invalid key gets 401. `tools/list` returns the same single
  `search_deepgram_knowledge_sources` tool as Paths A and B, so this is the hosted HTTP form of
  the same server — useful when the user has a key but cannot install anything. Pass the key as a
  header, or the client falls back to OAuth:

  ```sh
  claude mcp add deepgram-relay --transport http https://api.dx.deepgram.com/kapa/mcp \
    --header "Authorization: Token $DEEPGRAM_API_KEY"
  ```
- **`deepgram.mcp.kapa.ai` does not.** A Deepgram API key gets 401 with either scheme. OAuth is
  the only way in.

Neither is the zero-setup option — use `/_mcp/server` for that.

---

## Step 4: Confirm

- **Claude Code** — run `/reload-plugins` to activate immediately, no restart needed.
- **Cursor / Windsurf / Other** — the user may need to restart or reload their tool.

Then tell the user the server is configured, and check what it actually exposes before
describing it — have the client list its tools rather than naming tools from memory.

For Path C, add:

> Your tool can now search Deepgram's documentation directly — try asking about API
> parameters, voice agents, or model capabilities.

Link them to [Deepgram Agentic Tools](https://developers.deepgram.com/developer-tools/agentic-tools)
for more details. Its two kapa URLs, `https://api.dx.deepgram.com/kapa/mcp` and
`https://deepgram.mcp.kapa.ai`, require credentials: an unauthenticated `initialize` returns 401.
The Docs MCP server at `https://developers.deepgram.com/_mcp/server` is the credential-free path.

## Troubleshooting

**`Error: DEEPGRAM_API_KEY is not set in the configuration file (...config.yaml) or environment variable.`**
followed by `Run deepctl login to configure the CLI with your Deepgram account.`
→ Path A with no credentials. `dg mcp` exits 1 before serving anything. Run `dg login`, or set
`DEEPGRAM_API_KEY`. Confirm with `dg whoami`.

**`Error: No API key. Set DEEPGRAM_API_KEY or use --api-key.`**
→ Path B with no credentials. Export `DEEPGRAM_API_KEY`, put it in the server's `env` block, or
pass `--api-key`.

**`! Needs authentication` in `claude mcp list`, or HTTP 401 `{"status_code":401,"detail":"Authentication required"}` / `{"error":"invalid_token"}`**
→ You are pointed at a kapa endpoint with no credentials. Switch to
`https://developers.deepgram.com/_mcp/server`, which needs none. To stay on
`api.dx.deepgram.com/kapa/mcp`, add `--header "Authorization: Token $DEEPGRAM_API_KEY"` — that
endpoint accepts a Deepgram API key. On `deepgram.mcp.kapa.ai` an API key does not work; let the
client run its OAuth flow instead.

**`Server "deepgram-docs" is defined in multiple scopes with different endpoints`**
→ An earlier setup registered `deepgram-docs` at a kapa URL in user scope, and this one added a
different URL in project scope. OAuth tokens are stored per endpoint, so authenticating one does
not carry over. Keep one: `claude mcp remove deepgram-docs -s user` (or `-s project`). Check for
a pre-existing entry with `claude mcp get deepgram-docs` before adding, and pick a distinct
server name if the user wants to keep both.

**`ImportError` mentioning `streamablehttp_client` on startup**
→ An incompatible `mcp` package. `deepgram-mcp` imports `streamablehttp_client` from
`mcp.client.streamable_http`, which `mcp` 2.0 removed. Install into a clean environment, or pin
`mcp>=1.0.0,<2.0.0`. Installing `deepctl` pins this for you.

**The server connects but exposes fewer tools than expected**
→ Expected. Paths A and B fetch their tool list from Deepgram at runtime, so it reflects what
the API serves right now, not what the package version implies. Reconnect to pick up new tools.

**Anything else on Path A**
→ Verify `dg --version` works and `dg mcp` runs in a terminal without errors, then
`dg update --check-only` to see whether a newer release exists.

## Sources

- Deepgram CLI: <https://github.com/deepgram/cli>
- `deepgram-mcp`: <https://github.com/deepgram/mcp>
- Deepgram Agentic Tools: <https://developers.deepgram.com/developer-tools/agentic-tools>
````

- Previous: [starters](https://syn4pse.dev/terminal/deepgram-starters.md)
- Next: [recipes](https://syn4pse.dev/terminal/deepgram-recipes.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
