How teams should manage MCP setup

Why hand-editing every config breaks down

MCP makes agent tools portable, but the setup path is still fragmented. One teammate may hand-edit Claude Desktop JSON, another may configure a hosted connector, and another may keep a local stdio script in a private folder.

That works for a solo experiment. It fails for a team because no one can reliably answer which server URL is approved, which scopes are expected, who owns the connection, whether OAuth is healthy, or which harnesses are still using stale local config.

The practical setup flow

A team-safe MCP setup separates hosted-agent OAuth from local editor config while keeping both tied to the same workspace policy.

1. 1

   Publish one canonical workspace setup surface

   Document the approved MCP endpoint, supported clients, owner, admin contacts, expected scopes, and support diagnostics in one workspace page instead of asking every teammate to maintain their own notes.

2. 2

   Use hosted OAuth where the client supports it

   Claude, ChatGPT, Manus, Perplexity, and other hosted MCP clients should use the same remote MCP server URL plus OAuth when available, so user consent and connection state are visible instead of hidden in a copied token.

3. 3

   Use a local proxy for editors and CLIs

   Codex CLI, Claude Code, Cursor, Gemini CLI, and Antigravity should use the guided `npx fygment` setup where shipped. That flow installs a local authenticated MCP proxy such as `fygment mcp proxy` rather than making users hand-edit each target file from scratch.

4. 4

   Keep governance separate from secrets

   The team should govern metadata, ownership, health, and revoke controls. It should not claim to vault every third-party MCP secret or manage the full lifecycle of every MCP server package unless the product actually ships those controls.

Hosted-agent path

For hosted agents, the clean team path is one remote MCP URL: `https://fygment.dev/api/mcp`. The user pastes that URL into the hosted client connector flow and completes OAuth when the client supports it.

This keeps the public explanation crawlable while the actual workspace setup remains auth-aware: public docs can explain the pattern, but links and calls to action should send signed-in users to their workspace setup page for workspace-specific status and connection management.

Claude Web/Desktop custom connectors should use a display name such as Fygment, the bare remote MCP server URL, and OAuth discovery. Advanced OAuth Client ID and OAuth Client Secret fields should be left blank unless support provides static credentials.

Local editor path

For local editors and CLIs, the preferred path is `npx fygment`. The guided setup lets a user select targets such as Codex CLI, Claude Code, Cursor, Gemini CLI, and Antigravity, preview the config change, and install the local authenticated proxy where that target is supported.

The important team habit is that the workspace defines the approved setup intent, while each user keeps their local machine credentials local. A local proxy/setup flow reduces repeated manual edits without pretending every harness has identical remote MCP support.

Live now, alpha, and roadmap MCP capabilities

Availability matters because MCP setup is useful today, but Fygment should not overclaim full server lifecycle management.

Governance model

A managed MCP setup should record connection metadata such as client name, user, scopes, created time, update time, access expiry, refresh expiry, and health state. That metadata is what lets a team spot expired OAuth, abandoned clients, and support issues.

Owner/admin boundaries matter. Members can follow setup instructions and connect their own tools, while owners and admins should be the ones who manage workspace-level policy and revoke remote OAuth connections. Revoke controls should be visible enough to use, but not presented as a general-purpose secret-management system.

Firewall and bot controls are part of governance too. Hosted clients may fetch metadata and call MCP endpoints with user-agent patterns that differ from normal browser traffic, so edge rules need narrow allow paths rather than broad security bypasses.

Troubleshooting checklist

When setup fails, separate client configuration, OAuth, local proxy state, and edge security before changing product code.

1. 1

   Confirm the URL shape

   Hosted agents should use the bare remote MCP URL, such as `https://fygment.dev/api/mcp`. Do not add workspace slugs, query strings, API keys, or custom headers unless a support path explicitly asks for them.

2. 2

   Check OAuth and connection health

   If a hosted connector cannot list tools or needs reconnecting, review whether the OAuth connection is active, expiring soon, expired, or revoked on the workspace setup page.

3. 3

   Verify the local proxy

   For local clients, rerun `npx fygment`, confirm the selected target, and make sure the generated config points to the Fygment MCP proxy instead of an old hand-written command.

4. 4

   Review WAF and bot rules

   A common Claude/Cloudflare lesson is that the post-token MCP call can arrive as a `Claude-User` request to `POST /api/mcp`. If AI bot blocking is enabled, use a narrow rule for that endpoint rather than disabling protections broadly.

FAQ