agent MCP — Use Cases, Install & Live Demo

Why use it

Key features

OAuth 2.1 + scope-based auth out of the box
Hot-reload: edit config, new upstreams appear without restart
Audit logging on every tool call
Tag-based filtering so different clients see different tool sets
Runs via npx @1mcp/agent, binary, or Docker

Live Demo

What it looks like in practice

agent.replay ▶ ready

0/0

Install

Pick your client

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

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

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

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

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "agent": {
      "command": "npx",
      "args": [
        "-y",
        "agent"
      ],
      "_inferred": true
    }
  }
}

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

~/.continue/config.json

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

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

~/.config/zed/settings.json

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

Add to context_servers. Zed hot-reloads on save.

claude mcp add agent -- npx -y agent

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

Use Cases

Real-world ways to use agent

Run a multi-tenant MCP gateway for different teams

👤 Platform teams serving multiple squads with different tool needs ⏱ ~45 min advanced

When to use: Design and Eng need different MCPs, but you don't want to run two gateways.

Prerequisites

A host with Node 20+ or Docker — Any small VM
OAuth IdP (or use built-in for local) — Dex, Auth0, Okta — anything that speaks OIDC

Flow

Define scopes in the agent config

Draft an agent config where 'design' scope exposes figma and davinci-resolve MCPs, 'eng' scope exposes github, sentry, postgres.✓ Copied

→ Config with scoped upstream mappings
Wire OAuth

Connect the agent to our Auth0 tenant, map groups to scopes.✓ Copied

→ Users see only their scope's tools
Audit usage

Show me the last 24h of tool calls by user, grouped by tool name.✓ Copied

→ Usage report

Outcome: One gateway, per-team tool views, full audit trail.

Pitfalls

Scope design gets spaghetti fast — Start with 2-3 broad scopes (eng-read, eng-write, design) rather than per-tool scopes
Audit logs balloon disk usage — Rotate logs weekly or ship to a log aggregator

Combine with: github · sentry

Develop a custom MCP with hot-reload

👤 Builders iterating on their own MCP server ⏱ ~20 min intermediate

When to use: You're writing a new MCP and don't want to reload the IDE after every change.

Flow

Register your dev MCP under the agent

Add my local dev MCP at node ./my-mcp/dist/index.js under the agent config, tag it 'dev'.✓ Copied

→ Tool appears in client
Edit, save, retry

I changed the tool. Tell me if the new version is live without me restarting.✓ Copied

→ Hot-reload confirmed

Outcome: A fast inner loop for MCP development.

Pitfalls

Hot-reload can leak old tool handles if clients cache — For big interface changes, bounce the client anyway

Front an untrusted upstream MCP with sanitization

👤 Security-conscious admins running community MCPs ⏱ ~15 min intermediate

When to use: You want to try a community MCP but want belt-and-suspenders input guards.

Flow

Enable sanitization

Configure 1mcp agent to enable input sanitization on upstream 'community-x', block any tool returning an oversized payload.✓ Copied

→ Limits applied
Verify

Call a tool from that upstream and confirm sanitization log entries.✓ Copied

→ Log shows sanitized call

Outcome: A safer blast radius when experimenting with community tools.

Combinations

Pair with other MCPs for X10 leverage

agent + proxy-2

Compare feature-heavy 1mcp vs minimal tbxark/mcp-proxy

Run both 1mcp/agent and tbxark/mcp-proxy on the same host and compare tool-call latency through each.✓ Copied

agent + jetski

Stack analytics on top of 1mcp

Run 1mcp/agent behind Jetski to get both OAuth and prompt-level analytics.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_tools	(none)	Handshake — handled by clients	free
call_tool	name, args	Any invocation	1 upstream call
mcp_add	name, command, args	Add a new upstream dynamically (admin-only)	free

Cost & Limits

What this costs to run

API quota: None of its own; bounded by upstream quotas
Tokens per call: Small proxy overhead
Monetary: Free, MIT
Tip: Enable audit only on write-capable upstreams — read-only logs fill disk fast for no benefit.

Security

Permissions, secrets, blast radius

Minimum scopes: OAuth client config + upstream server credentials

Credential storage: Env vars and config file; use a secret manager for production

Data egress: Agent forwards to configured upstreams only

Never grant: admin scope to end users — reserve for platform team

Rotate audit logs — long-running agents accumulate GB of tool-call history.
OAuth scopes are only as safe as your IdP group mapping; audit who's in which group quarterly.

Troubleshooting

Common errors and fixes

Hot reload didn't pick up my config change

Check the file watcher has permission on the mounted dir (Docker bind mounts on macOS can miss events). Fall back to SIGHUP.

Verify: docker exec agent kill -HUP 1

OAuth token rejected

Scope claim doesn't map to any configured scope. Check agent logs for the claim and align config.

Verify: Decode JWT at jwt.io

Upstream MCP fails health check

Run the upstream command manually to see its stderr. Agent logs only report exit code.

Verify: docker exec agent sh -c '<upstream command>'

Tool list empty for a user

That user's scopes don't match any tool's required scope tags.

Verify: Check scope mapping in config vs JWT claims

Alternatives

agent vs others

Alternative	When to use it instead	Tradeoff
tbxark/mcp-proxy	You want a minimal Go binary without OAuth	No auth, no hot-reload, no scopes
Jetski	You want full analytics dashboards and DCR	K8s + Postgres infrastructure required

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills