agent MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

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

Demo ao vivo

Como fica na prática

agent.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

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

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

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

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

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

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

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

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

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

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

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add agent -- npx -y agent

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: agent

Run a multi-tenant MCP gateway for different teams

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

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

Pré-requisitos

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

Fluxo

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.✓ Copiado

→ Config with scoped upstream mappings
Wire OAuth

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

→ Users see only their scope's tools
Audit usage

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

→ Usage report

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

Armadilhas

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 com: github · sentry

Develop a custom MCP with hot-reload

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

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

Fluxo

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'.✓ Copiado

→ Tool appears in client
Edit, save, retry

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

→ Hot-reload confirmed

Resultado: A fast inner loop for MCP development.

Armadilhas

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

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

Fluxo

Enable sanitization

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

→ Limits applied
Verify

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

→ Log shows sanitized call

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

Combinações

Combine com outros MCPs para 10× de alavancagem

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.✓ Copiado

agent + jetski

Stack analytics on top of 1mcp

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

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
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

Custo e limites

O que custa rodar

Cota de API: None of its own; bounded by upstream quotas
Tokens por chamada: Small proxy overhead
Monetário: Free, MIT
Dica: Enable audit only on write-capable upstreams — read-only logs fill disk fast for no benefit.

Segurança

Permissões, segredos, alcance

Escopos mínimos: OAuth client config + upstream server credentials

Armazenamento de credenciais: Env vars and config file; use a secret manager for production

Saída de dados: Agent forwards to configured upstreams only

Nunca conceda: 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.

Solução de problemas

Erros comuns e correções

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.

Verificar: 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.

Verificar: 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.

Verificar: 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.

Verificar: Check scope mapping in config vs JWT claims

Alternativas

agent vs. outros

Alternativa	Quando usar	Troca
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

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills