Connect an agent

Model Context Protocol

One Streamable HTTP endpoint exposes eight 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 → Settings → 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.

muxcode

muxcode 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 muxcode 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 Pro+, 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

Eight 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
`get_context`	`task`	Optional `repositories`, `revisions`, `changedPaths`, `tokenBudget` (1,024–16,000) and `freshness`. One packet of evidence for the task, bound to the indexed commits, with approved findings and a `receiptId`.	Every plan; semantic matches on Pro and Pro+.
`record_context_outcome`	`receiptId`, `repository`, `revision`, `statement`	Optional `paths` (the files the finding rests on), `scope` and `retentionDays`. Proposes a finding; a workspace owner approves it in mux.	Every plan.
`trace_code`	`repository`, `path`	Optional `symbol` and `limit`. One file on the code graph: what it defines, imports and is imported by, its tests, the routes it calls and the files in any repository that call the routes it serves, and its owners.	Every 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 Pro+.
`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 Pro+.

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

Context for a task

Start a task with get_context: one call returns the evidence for it across the workspace’s repositories, each piece tied to the commit it was read at, and any findings a workspace owner approved.

By default the packet must match each branch’s latest commit. When the index is behind, a client on MCP 2026-07-28 that can answer a form is asked whether the older commit will do; other clients get context_stale. Pass freshness: "allow_stale" to take the older commit without asking.
record_context_outcome proposes a finding from a packet’s receiptId. Name in paths the few files the finding rests on. After a push, an approved finding moves to the new commit while every cited file is unchanged; a change to one marks it outdated.
The packet follows the code graph two hops from its strongest matches: imports, tests, and the routes one repository calls in another. relationships lists those edges, each marked candidate because it is read from source text, not a compiler.
trace_code answers the same graph for one file, or one symbol in it.
Retrieved text, findings included, is evidence to check, not instructions.

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 Pro+. 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.
`graph_unavailable`	`trace_code` before the index has written its code graph at the current commit. Refresh the index, then trace again; `get_context` answers without graph edges and names the same omission.
`context_stale`	The index is behind the latest commit of a branch the packet needs. Retry after the refresh, or pass `freshness: “allow_stale”`.
`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 → Settings → 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}}