Archestra MCP Gateway for Claude Code: Setup Guide

Archestra’s open-source repository had 4,100 GitHub stars on August 9, 2026. The more useful number for Claude Code users is one: an Archestra MCP Gateway for Claude Code can replace a small zoo of separately configured MCP servers with one managed endpoint. Fewer JSON files are nice. Fewer mystery credentials are nicer.

This guide sets up that endpoint, scopes its tools, connects Claude Code, verifies a real call, and preserves a clean exit. That last half matters. Seeing a server name inside /mcp proves that registration worked; it does not prove that the right user can reach the right tool with the right credential.

What an Archestra gateway changes

A direct MCP setup gives Claude Code one connection per server. That is perfectly sensible for one developer and one tool. Add GitHub, Jira, an internal database, and the upstream MCP server you built on Cloudflare, however, and client configuration becomes an archaeological site.

Archestra puts a gateway in the middle. Claude Code talks to one URL; the gateway exposes a curated tool set, handles client authentication, resolves downstream credentials, and records tool calls. The open-source Archestra repository describes the broader platform, but the useful mental model is smaller: the gateway is a switchboard with a guest list.

Centralization is not the same as least privilege. If you expose every installed tool to every user, you have created one very convenient blast radius. The real definition of done is four-part: Claude Code connects, only intended tools appear, a read-only call runs under the intended identity, and the connection can be removed without config surgery.

Decision	Direct MCP connection	Archestra gateway
Client setup	One entry per server	One endpoint for a curated tool set
Credentials	Configured at each client or server	Resolved behind the gateway
Access changes	Edit each affected client	Change gateway tools or visibility
Audit path	Depends on each server	Central tool-call logs

Prepare the local Archestra and Claude Code setup

You need Docker, a working claude CLI on your PATH, and permission to create or edit an Archestra gateway. If your organization already runs Archestra, skip the container and ask the administrator which environment and team scope to use.

Run Archestra locally

For evaluation, the official Docker quickstart uses an all-in-one image:

docker pull archestra/platform:latest

docker run \
  -p 127.0.0.1:9000:9000 \
  -p 127.0.0.1:3000:3000 \
  -e ARCHESTRA_QUICKSTART=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v archestra-postgres-data:/var/lib/postgresql/data \
  -v archestra-app-data:/app/data \
  archestra/platform

The UI runs at http://localhost:3000; the API listens on port 9000. Both bind to 127.0.0.1 in this command, so the quickstart does not quietly advertise an admin console to your network. Keep it that way for a laptop test.

Inside Archestra, open the MCP Registry and install an MCP server, or identify one already available to your team. Choose something with a harmless read operation for the first test—listing documentation or reading a repository issue beats making “delete production” your connectivity probe.

Configure the Archestra MCP Gateway for Claude Code

Open MCPs → Gateways and create a gateway. According to Archestra’s MCP Gateway requirements, a usable gateway needs at least one assigned tool, a supported authentication path, and visibility that includes the intended callers.

1. Name the gateway for its job. engineering-read-tools is more informative than mcp-final-v3.
2. Set visibility deliberately. Use personal scope for a private experiment, team scope for a defined group, or organization scope only when broad access is intentional.
3. Assign a small tool set. Start with the read-only tool selected above. Add write actions after the identity test passes.
4. Choose credential resolution. Decide whether calls should use each person’s connection or a shared service account.

Choose the credential boundary

Archestra separates the credential Claude Code uses to enter the gateway from the credential the gateway uses for an upstream service. Its two-layer authentication model lets the same endpoint expose, for example, a GitHub tool backed by a user’s OAuth connection and an internal server that needs no external credential.

That separation also keeps downstream secrets out of Claude Code’s MCP entry. The client proves it may call the gateway; Archestra decides what credential is appropriate only when a tool executes. This does not make credentials magically safe, but it removes the need to distribute every upstream token to every developer laptop—a meaningful reduction in secret confetti.

Use Resolve at call time when the action should follow the human caller’s access—personal GitHub issues are the obvious case. Pin a team or organization connection only when everyone is meant to act through one shared service account. Shared identity is sometimes a feature. Accidental shared identity is an incident report with better typography.

This is the main difference from a direct Claude Code MCP setup. Direct registration answers “where is the server?” A gateway must also answer “who is calling, what may they see, and whose downstream account performs the action?” Save the gateway only after all three answers are explicit.

Connect Claude Code without leaking the setup secret

Open Archestra’s Connect page, select Claude Code, choose the gateway, and generate the setup command. The Claude Code connection guide says the generated URL expires after 15 minutes and is consumed on its first fetch. Treat the command as a secret: do not paste it into tickets, chat logs, or a repository.

The fast path pipes the script into a shell. The inspect-first path adds one download and one review step; in return, you see what will touch your configuration before it runs:

curl -fsSL '<one-time-setup-url>' -o archestra-setup.sh
less archestra-setup.sh
bash archestra-setup.sh

The generated script registers the HTTP endpoint using the equivalent of:

claude mcp add --transport http <name> <gateway-url>

It also makes a one-time backup before changing managed configuration. Now start Claude Code, run /mcp, select the gateway, and choose Authenticate. Complete the Archestra consent flow in the browser. If the server still reads disabled, select Enable.

Verify the gateway, then troubleshoot or remove it

Ask Claude Code to run the read-only tool you assigned. Confirm the output in Claude Code, then inspect the Archestra tool-call logs for the gateway, tool name, and caller identity. “Connected” is plumbing; a correctly attributed call is the test.

1. Ask Claude to list the tools exposed by the gateway, then compare that list with the assignments in Archestra.
2. Run one read-only action whose result you can independently recognize, such as fetching a known issue or documentation page.
3. Open the gateway logs and confirm the call appears under the expected user or shared service account.
4. Temporarily remove that tool from the gateway and confirm Claude Code can no longer call it, then restore it if needed.

The fourth check is easy to skip and unusually valuable. It proves policy changes propagate through the gateway instead of leaving a stale capability in the client. Security controls that work only in diagrams tend to have short, exciting careers.

Symptom	Check	Fix
Gateway appears, no tools	Tool assignment and visibility	Assign a tool and include the caller’s scope
Server is disabled	/mcp status	Authenticate, then choose Enable
Setup URL fails	Age or previous fetch	Generate a fresh one-time command
Wrong upstream identity	Pinned vs. resolved credential	Switch to the intended per-user or shared model
Gateway is unavailable	Archestra health and endpoint	Restore service or disconnect the remote

To remove the client registration, use Archestra’s Disconnect panel or run claude mcp remove <name>. Restore the documented .archestra-backup only if you also need to undo managed configuration changes. For controls beyond the gateway, use the six-layer agent security checklist.

One endpoint is not the finish line

The unresolved question is operational: can one gateway remain a clean policy boundary as a team adds dozens of MCP servers, or does tool sprawl simply move from the client into the control plane?

The answer starts with how this first connection is built. A single endpoint is convenience; a verified identity and a deliberately small tool set are control. Archestra supplies the control plane, but the policy still belongs to the person choosing the checkboxes.

The next upgrade checkpoint is any Claude Code migration to the MCP 2026-07-28 revision, with its stateless discovery and task behavior. Before that client rollout, capture today’s tool list and one known-good trace. Afterward, the durable test stays wonderfully unglamorous: one safe tool, one known caller, one log entry you can explain.