agent MCP — 使用场景, 安装 & 实时演示

为什么要用

核心特性

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

实时演示

实际使用效果

agent.replay ▶ 就绪

0/0

安装

选择你的客户端

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

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

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

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

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

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit

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

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

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

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json

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

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json

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

加入 context_servers。Zed 保存后热重载。

claude mcp add agent -- npx -y agent

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： agent

Run a multi-tenant MCP gateway for different teams

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

何时使用： Design and Eng need different MCPs, but you don't want to run two gateways.

前置条件

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

步骤

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.✓ 已复制

→ Config with scoped upstream mappings
Wire OAuth

Connect the agent to our Auth0 tenant, map groups to scopes.✓ 已复制

→ Users see only their scope's tools
Audit usage

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

→ Usage report

结果： One gateway, per-team tool views, full audit trail.

注意事项

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

搭配使用： github · sentry

Develop a custom MCP with hot-reload

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

何时使用： You're writing a new MCP and don't want to reload the IDE after every change.

步骤

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'.✓ 已复制

→ Tool appears in client
Edit, save, retry

I changed the tool. Tell me if the new version is live without me restarting.✓ 已复制

→ Hot-reload confirmed

结果： A fast inner loop for MCP development.

注意事项

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

何时使用： You want to try a community MCP but want belt-and-suspenders input guards.

步骤

Enable sanitization

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

→ Limits applied
Verify

Call a tool from that upstream and confirm sanitization log entries.✓ 已复制

→ Log shows sanitized call

结果： A safer blast radius when experimenting with community tools.

组合

与其他 MCP 搭配，撬动十倍杠杆

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.✓ 已复制

agent + jetski

Stack analytics on top of 1mcp

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

工具

此 MCP 暴露的能力

工具	输入参数	何时调用	成本
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

成本与限制

运行它的成本

API 配额: None of its own; bounded by upstream quotas
每次调用 Token 数: Small proxy overhead
费用: Free, MIT
提示: Enable audit only on write-capable upstreams — read-only logs fill disk fast for no benefit.

安全

权限、密钥、影响范围

最小权限： OAuth client config + upstream server credentials

凭据存储： Env vars and config file; use a secret manager for production

数据出站： Agent forwards to configured upstreams only

切勿授予： 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.

故障排查

常见错误与修复

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.

验证： 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.

验证： 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.

验证： 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.

验证： Check scope mapping in config vs JWT claims

替代方案

agent 对比其他方案

替代方案	何时用它替代	权衡
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

agent

为什么要用

核心特性

实时演示

实际使用效果

安装

选择你的客户端

使用场景

实战用法： agent

Run a multi-tenant MCP gateway for different teams

前置条件

步骤

注意事项

Develop a custom MCP with hot-reload

步骤

注意事项

Front an untrusted upstream MCP with sanitization

步骤

组合

与其他 MCP 搭配，撬动十倍杠杆

工具

此 MCP 暴露的能力

成本与限制

运行它的成本

安全

权限、密钥、影响范围

故障排查

常见错误与修复

替代方案

agent 对比其他方案

更多

资源