Archestra (MCP server) — Use Cases, Install & Live Demo

Why use it

Key features

Private MCP registry — curate which servers your org allows
Gateway: one URL fronts many MCPs, with SSO + token auth
Per-tool guardrails (e.g. no GitHub.delete_repo even though the server exposes it)
Audit log of every tool call, prompt, and result
Self-hosted; runs in Docker / Kubernetes
Web admin UI for ops

Live Demo

What it looks like in practice

archestra-mcp.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "archestra-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "archestra"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "archestra-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "archestra"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "archestra-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "archestra"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "archestra-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "archestra"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "archestra-mcp",
      "command": "npx",
      "args": [
        "-y",
        "archestra"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "archestra-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "archestra"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add archestra-mcp -- npx -y archestra

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Archestra

Roll out MCP to an org without giving every dev raw API keys

👤 Platform / IT / security teams ⏱ ~90 min advanced

When to use: Your devs want MCP but you can't have 200 PATs floating around in laptops.

Prerequisites

A host (VM or k8s) and SSO provider (Okta/Entra/Google) — Standard infra — Archestra brings its own postgres + redis

Flow

Deploy the gateway

Walk me through deploying Archestra via Docker Compose. Bind to https://mcp.example.com and configure Okta OIDC.✓ Copied

→ Compose file written; gateway responds at the URL with login redirect
Add servers

Add github, postgres, and slack MCPs to the registry. Store creds in Archestra vault, not env vars.✓ Copied

→ Three servers listed; per-server creds stored encrypted
Provision a user

Give engineering group access to github (read-only) and postgres (read-only). No slack.✓ Copied

→ Access policy applied; smoke test from a dev's claude config works

Outcome: Whole org talks to one MCP URL; you control which tools each role can call.

Pitfalls

SSO token expiry kills active Claude sessions — Configure refresh-token mode in OIDC; Archestra will rotate transparently

Block dangerous tools at the gateway, not in client config

👤 Security/compliance teams ⏱ ~30 min intermediate

When to use: Some MCPs ship with destructive tools (delete repo, drop table) you simply never want exposed.

Flow

Inventory tools

List every tool exposed across registered MCPs.✓ Copied

→ Flat tool list, hundreds of entries
Define policy

Block: github.delete_repo, postgres.execute_ddl, slack.delete_message. Allow everything else.✓ Copied

→ Policy created; affected tools marked blocked
Verify

Have a Claude session try github.delete_repo. Should fail at the gateway with a clear message.✓ Copied

→ Call rejected; audit log entry

Outcome: A policy you can show your CISO that says 'these tools cannot be invoked at the perimeter'.

Pitfalls

MCP server adds a new tool in an upgrade — Archestra surfaces 'new tool detected' on registry refresh — review before allowing

Get a per-user audit trail of every MCP call

👤 Ops, audit, post-incident ⏱ ~15 min intermediate

When to use: Something weird happened in prod and you need to know which agent ran which tool.

Flow

Find the window

Pull all calls between 14:00 and 15:30 today. Group by user.✓ Copied

→ Table per user; each tool + arg + result preview
Drill into anomalies

Anything that looks unusual — delete operations, off-hour activity?✓ Copied

→ Highlighted suspicious entries
Export

Export the slice as CSV for compliance.✓ Copied

→ CSV written

Outcome: A defensible audit trail without reinventing one.

Pitfalls

Default retention is 30 days — Bump retention via config or stream to your SIEM

Combine with: filesystem

Combinations

Pair with other MCPs for X10 leverage

archestra-mcp + filesystem

Export audit slices for compliance archives

Export this week's audit log to /audit/$(date +%V).csv.✓ Copied

archestra-mcp + github

Track infra config (Archestra config-as-code)

Diff my live policy with /repo/archestra/policy.yaml and open a PR if drifted.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_servers	(none)	Discover what's available	free
list_tools	server?	Surface tools across all servers	free
audit_query	from, to, user?, server?, tool?	Forensic / compliance	1 DB query
policy_set	scope, allow[], deny[]	Adjust per-role / per-tool policies	free

Cost & Limits

What this costs to run

API quota: Self-hosted; bound by your infra
Tokens per call: Adds tiny overhead per call
Monetary: Free OSS; commercial support available
Tip: Keep audit retention bounded (30–90d) and stream older to S3 for cheap long-term storage

Security

Permissions, secrets, blast radius

Minimum scopes: Admin to configure End users use SSO scopes only

Credential storage: Archestra Vault (encrypted at rest); never raw env in user clients

Data egress: Stays in your infra; outbound only to the MCP servers you registered

Never grant: Admin to ordinary developers

Anyone with admin can read vault secrets — treat that role like prod DB access

Troubleshooting

Common errors and fixes

OIDC redirect loop

Confirm redirect_uri includes the trailing slash; some IdPs are strict

Verify: Test with idpinitiated SSO — if that works, redirect URI is the issue

Tool blocked unexpectedly

Check policy precedence — deny rules win over allow

Verify: Use `policy_test` with the role + tool to see resolved decision

Server unreachable

Check the registered MCP's stdio/http transport — Archestra logs the underlying error

Verify: Run the MCP standalone with the same creds

Alternatives

Archestra vs others

Alternative	When to use it instead	Tradeoff
MCPJungle	You want a lighter-weight 'all servers behind one endpoint' without enterprise bells	MCPJungle is simpler; Archestra adds policy + audit + SSO
samanhappy/mcphub	Self-hosted OSS hub with good UI is enough	MCPHub is more dev-focused; Archestra targets enterprise governance

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills