Connect an agent

Model Context Protocol

One Streamable HTTP endpoint exposes five tools over your workspace’s code index. Authentication is a workspace API key sent as a Bearer token.

Endpoint and workspace key

Server: https://usemux.com/mcp
Authorization: Bearer hk_live_…

In mux, open Manage account → Access, choose principal agent, role agent, give the key a recognizable name, set an expiry, then mint it. Copy the plaintext hk_live_… value immediately; mux shows it once.

Store the raw hk_… value in MUX_API_KEY. Do not include the word Bearer in the variable, commit the value, or paste it into chat. The key is scoped to one workspace, so no tool takes a workspace argument: the key names it. Self-hosters should replace the host but keep the /mcp path.

Configure a client

Codex

Codex can source a remote MCP Bearer token directly from an environment variable:

export MUX_API_KEY='hk_live_…'
codex mcp add mux \
  --url https://usemux.com/mcp \
  --bearer-token-env-var MUX_API_KEY
codex mcp get mux

The equivalent ~/.codex/config.toml entry is:

[mcp_servers.mux]
url = "https://usemux.com/mcp"
bearer_token_env_var = "MUX_API_KEY"

Launch Codex from an environment where MUX_API_KEY is set. This shape is defined by the current Codex MCP configuration reference and codex mcp command reference.

Claude Code

For a project configuration, put the variable reference—not the token—in .mcp.json:

{
  "mcpServers": {
    "mux": {
      "type": "http",
      "url": "https://usemux.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MUX_API_KEY}"
      }
    }
  }
}

Set MUX_API_KEY before launching Claude Code, approve the project server when prompted, then run /mcp to inspect its status. Claude Code supports environment expansion in .mcp.json; see the current Claude Code MCP reference.

For a quick local configuration, the CLI also accepts an HTTP header:

export MUX_API_KEY='hk_live_…'
claude mcp add --transport http mux https://usemux.com/mcp \
  --header "Authorization: Bearer $MUX_API_KEY"
claude mcp get mux

That command resolves the variable before saving the server, so the resulting local configuration contains the token. Prefer the .mcp.json variable reference, or use a short-lived mux key and protect the local config file.

GitHub Copilot CLI

Copilot CLI supports remote HTTP servers and explicit headers:

export MUX_API_KEY='hk_live_…'
copilot mcp add --transport http \
  --header "Authorization: Bearer $MUX_API_KEY" \
  --tools "*" \
  mux https://usemux.com/mcp
copilot mcp get mux

Copilot writes the resolved header to ~/.copilot/mcp-config.json. Keep that file private, use an expiring workspace key, and revoke the key in mux when the client no longer needs it. The syntax comes from GitHub’s current Copilot CLI MCP guide.

Fluxcode

Fluxcode signs itself in: it asks mux for a code, you approve the request in the browser, and mux mints the key for that device. Do not paste a key into Fluxcode by hand.

Claude custom connectors and Claude Desktop

The endpoint is not yet compatible with Claude’s account-brokered custom remote connector flow used by Claude and Claude Desktop. That surface accepts a server URL and uses an authless connection or MCP OAuth discovery; it does not offer a field for a static Authorization header. Only hk_… Bearer keys are validated, and MCP OAuth metadata is not advertised.

Use Claude Code’s HTTP/header configuration today. Adding OAuth safely requires consent, account linking, scoped token issuance, refresh, and revocation; it is planned rather than silently approximated. Anthropic documents the current flow in Get started with custom connectors using remote MCP. No Cursor configuration is shown here because a current, verified static-header setup was not established.

Verify the connection

Run this sequence before asking the agent to search:

Call corpus_status with {}. It answers from stored state and never wakes the index.
Call list_repositories with {} and copy a repository name for the filters below.
Call grep_code or, on Pro and Team, search_code.

{
  "name": "corpus_status",
  "arguments": {}
}

A workspace that has chosen no repository answers indexed: false rather than failing, so a fresh workspace still proves the connection.

Tool catalog

Five tools, each scoped to the workspace the key belongs to. Query and question text is capped at 4,000 characters, patterns at 2,000, and limit at 50. Tools return compact JSON; API error envelopes stay MCP tool errors with isError: true.

Tool	Required arguments	Optional arguments / result	Plan
`corpus_status`	none (`{}`)	Whether the workspace has an index, its repositories and their state, the last refresh, the embedding version, the plan and its repository limit.	Every plan.
`list_repositories`	none (`{}`)	The indexed repositories with branch and index state. Pass a name back as the `repository` filter.	Every plan.
`grep_code`	`pattern`	Optional `repository`, `language`, and `path` prefix inside the corpus. Structural match against the syntax tree, not a regular expression. Returns repository, path, start and end lines, score, and an excerpt.	Every plan.
`search_code`	`query`	Optional `limit`, `repository`, `language`, and `path`. Ranked matches by meaning with the same fields.	Pro and Team.
`ask_code`	`query`	The passages that bear on the question, as `grounding`, with `answer` null: your agent reads them and writes the answer.	Pro and Team.

{
  "name": "grep_code",
  "arguments": {
    "pattern": "fetch($X)",
    "repository": "acme/platform",
    "language": "typescript"
  }
}

Choose the search surface

grep_code when you know the shape of the code: a call, a signature, a literal construct. It is exact, and it is on every plan.
search_code when you know what the code does but not what it is called.
ask_code for “how does X work” over several files at once. It returns the passages to read, not a written answer; use the other two to find a specific symbol.

Every match carries repository, path, line, endLine, score, excerpt, and the headSha the excerpt was read at. Matches from search_code also carry language; a truncated grep_code result sets truncated: true.

Refusals

Symptom	Meaning and action
`401 unauthenticated`	The endpoint did not receive a valid active key. Confirm the value begins `hk_`, has not expired or been revoked, and is present in the environment that launched the client. Codex’s variable contains only the key; its client adds `Bearer`.
`plan_refused`	Semantic search is included with Pro and Team. Use `grep_code`, or change the plan in mux.
`no_repositories`	No repository has been chosen for this workspace’s index yet. Choose one in Graph & Index.
`403 forbidden`	The key’s role is too weak for this workspace, or the key belongs to another workspace.
`429` rate limited	The organization hit its per-minute burst bucket or its monthly API ceiling. Honor `Retry-After`; a body scope of `monthly` resets at the next UTC month.
`index_unavailable`	The hosted index did not answer. Retry in a moment; `corpus_status` still answers, because it reads stored state.
Connected, but no tools	Configure `type: “http”`/Streamable HTTP rather than legacy SSE, inspect the client’s MCP status command, and restart the client after changing its environment.

When a key may have leaked, revoke it in Manage account → Access, mint a replacement with an expiry, update the environment, and restart the client.

Worked call

{"name":"search_code","arguments":{"query":"where do we verify the GitHub webhook signature","limit":10}}