Skip to content

Team Deployment

devlomingo edited this page Nov 16, 2026 · 1 revision

Team deployment

The defaults suit one person on one machine. For a team, run Toolsmith as a shared HTTP gateway.

1. One token per agent

Each agent gets its own token, so approvals, rate limits and traces are bound to it:

"server": {
  "host": "0.0.0.0",
  "mcpToken": "${env:TOOLSMITH_MCP_TOKEN}",
  "adminToken": "${env:TOOLSMITH_ADMIN_TOKEN}",
  "clients": [
    { "name": "support-bot", "token": "${env:SUPPORT_BOT_TOKEN}",
      "exposure": { "tools": ["shop__get*", "flow__*"] } },
    { "name": "ops-agent", "token": "${env:OPS_AGENT_TOKEN}",
      "rateLimit": { "requestsPerSecond": 5, "burst": 20 } }
  ]
}

exposure.tools is an allow-list of globs, enforced on every call.

2. Or sign in with OAuth 2.1

If you run an authorization server, the gateway can accept its JWT access tokens directly:

"oauth": {
  "issuer": "https://auth.example.com",
  "resource": "https://tools.example.com/mcp",
  "requiredScopes": ["mcp:tools"],
  "exposure": { "tools": ["shop__get*"] },
  "clients": [{ "clientId": "reporting-agent", "exposure": { "tools": ["flow__*"] } }]
}

MCP clients discover the issuer from the gateway's 401 response and sign the user in themselves. Each user of each client app is its own identity, so approvals are never shared between users. Static tokens keep working alongside OAuth.

3. Several nodes with PostgreSQL

"database": { "url": "${env:DATABASE_URL}", "poolSize": 10 }

All nodes share the registry, traces, approvals and audit log. A tool published or disabled on one node reaches the others within about 1.5 s, and a per-call approval is spent exactly once across nodes. Tested with PostgreSQL 17. Add ?sslmode=require for a remote database.

Per-node state to know about:

  • Rate limits count per node: N nodes allow up to N× the configured rate.
  • In-client approval prompts need sticky sessions; otherwise they fall back to the dashboard.

4. Large catalogs

When you aggregate many APIs and MCP servers, keep each agent's tool list short:

"exposure": { "list": "search", "pinned": ["flow__*"] }

Agents then find other tools on demand with toolsmith__search_tools.

5. Observability

Send spans to any OpenTelemetry collector:

"telemetry": { "otlpEndpoint": "http://localhost:4318" }

Results are never exported; arguments only if exportArguments is set.

Exposing the gateway

  • Bind beyond loopback only behind TLS (a reverse proxy).
  • Keep the admin token separate from client tokens; the dashboard sign-in link is printed only to an interactive terminal.

Full reference: CONFIGURATION.md.

Clone this wiki locally