Shared MCP Workspaces for Teams

Make the workspace the boundary

The useful unit for team adoption is not a developer's laptop config. It is a workspace that owns connections to GitHub, Linear, Postgres, Drive, internal APIs and other systems, then exposes the subset an agent may use. MCP already gives you a common protocol surface: clients discover tools with JSON-RPC tools/list and invoke them with tools/call. A workspace endpoint turns those protocol messages into governed access rather than asking every teammate to maintain the same list of upstream servers.

The first design decision is ownership. A personal MCP server can be experimental, short-lived and named however the developer likes. A team endpoint needs stable source names, a reviewer for each source, a credential owner and a policy for reads versus writes. That puts it closer to an integration layer than an editor preference. If you are still deciding whether this belongs in a gateway, compare the broader boundary in the MCP gateway guide and the naming trade-offs in aggregator versus registry versus gateway.

The team benefit is mundane and important: adding a new issue tracker, rotating an upstream token or removing write access should not require a scavenger hunt through Claude Code, Cursor, VS Code, CI profiles and individual home directories. Those clients should point at the workspace. The workspace should decide what the current caller can see and call.

Keep client files boring

A good shared setup makes each AI client carry only the endpoint, a server name and a caller credential. Claude Code can add a remote HTTP MCP server from the CLI. Project-scoped Claude Code servers can also be stored in a repository root .mcp.json, which is useful when the team wants the same server entry reviewed in source control.

claude mcp add --transport http workspace --scope project https://mcp.example.com/agent/mcp \
  --header "Authorization: Bearer $WORKSPACE_MCP_KEY"

Cursor uses .cursor/mcp.json for project-specific MCP configuration and ~/.cursor/mcp.json for global configuration. For a team repository, commit the URL and interpolate the credential from the developer's environment:

{
  "mcpServers": {
    "workspace": {
      "url": "https://mcp.example.com/agent/mcp",
      "headers": {
        "Authorization": "Bearer ${env:WORKSPACE_MCP_KEY}"
      }
    }
  }
}

VS Code supports workspace MCP configuration too. Its .vscode/mcp.json format uses a top-level servers object, while portable workspace configuration can use a root .mcp.json in compatible tools. Keep secrets out of the committed file:

{
  "servers": {
    "workspace": {
      "type": "http",
      "url": "https://mcp.example.com/agent/mcp"
    }
  }
}

The exact syntax differs, but the invariant should not: one workspace endpoint, no pasted upstream tokens, and no direct database or SaaS credentials in the client file.

Model membership as credentials

Do not confuse a shared endpoint with shared authority. The endpoint can be common while permissions stay caller-specific. The MCP tools specification allows the returned tool set to vary by the authorization presented on the request, so a read-only engineering key and a release-manager key can receive different callable tools from the same URL. That is the core pattern for teams: the workspace is shared; the grant is not.

Use a small matrix before adding sources. Each row should include source name, owner, credential type, read tools, write tools, default approval behavior and log retention expectation. If the source is an upstream MCP server, record whether its tool names need namespacing. If it is a generated connector, record the generation boundary, such as read-only SELECT queries or GET-only HTTP operations. If the source uses OAuth, keep the OAuth grant tied to a workspace source and make agent-facing credentials narrower than the upstream account whenever possible.

This matrix also prevents a common failure: a team calls the endpoint shared, then hands every developer the same all-powerful bearer token. That only centralizes the blast radius. The safer version gives each agent or user a key whose source access and write grant match the job.

Validate the protocol path

Before asking an agent to solve a real incident, test the workspace endpoint with the protocol messages the client will send. Tool discovery should be deterministic, reviewable and small enough for the model to choose from. If the workspace reveals sources on demand, the first list can expose only navigation tools and already-opened sources.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Then test a permitted read. The call should include one tool name and a concrete argument object, and the audit log should show the presented credential, source, tool, decision, duration and result class.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "issues.search",
    "arguments": {
      "query": "checkout timeout",
      "limit": 5
    }
  }
}

Finally test a denied call, not just a missing tool. A useful team workspace tells the operator that the source exists but the caller lacks the write grant, instead of making the model infer policy from an empty list. That distinction matters during onboarding because a teammate can tell whether they need access, the source is down, or the integration was never connected.

Also test client caching behavior. Some clients keep the first tool list for a session, so a workspace that enables a source after startup needs either a refreshed list or a stable wrapper call that can address an opened source. Treat that as a rollout requirement, not as a polish detail.

Separate shared config from shared secrets

The repository can safely share endpoint configuration, but it should not share production secrets. Use environment interpolation, local secret stores or the client's OAuth flow for the caller credential. In VS Code, workspace trust matters because workspace MCP configuration can start servers; review workspace MCP files before trusting an unfamiliar repository. In Cursor, team distribution and allowlisting are different controls: distribution makes servers available, while policy decides what is approved. In Claude Code, project scope helps a team use the same entry, but each user still needs to authenticate appropriately.

For upstream systems, rotate at the workspace boundary. If a GitHub token, Linear OAuth grant or internal API key changes, the client URL should remain stable. That is the same operational argument behind credential rotation without touching every agent config. It also makes offboarding clearer: disable the user's workspace key, not a collection of hidden MCP entries across several tools.

Write down the few things every teammate should know: where the client file lives, how to set the local key, who owns each source, how to request a new grant and where to look when a tool call fails. Avoid asking people to memorize the full upstream topology. A shared workspace should make the integration map visible without making every developer an integration maintainer.

How SPYN3 handles team workspaces

A SPYN3 workspace has four roles: owner, admin, member and viewer. Teammates join through an emailed invitation. People share the workspace's connections, but agents should not share keys: give each person or job its own key, limited to the sources it needs. The call log then records which key made each call, and revoking one person's key leaves everyone else's agents working.

Roll out with a team checklist

Start with one repository, one read-only credential class and two sources. Pick a source everyone recognizes, such as the issue tracker, and one source that proves scoping, such as read-only database views or picked files. Have two teammates connect from different clients and compare what they can discover and call. The endpoint URL should stay the same, while tool visibility and denials reflect each credential.

1. Commit only the shared endpoint entry and variable references.
2. Issue separate credentials for at least two roles.
3. Confirm tools/list returns the expected small surface for each credential.
4. Run one allowed read call and one denied write call per role.
5. Break or expire one upstream connection and confirm the failure is visible in the agent result and the operator log.
6. Remove old direct MCP entries after the workspace path passes.

The last step is cultural: new sources should enter through the workspace review, not through a one-off editor config because somebody was moving fast. Exceptions are fine for experiments, but label them local and temporary. Once a source becomes part of team work, give it a stable name, an owner, scoped credentials and auditability. That is what lets agents help across systems without turning every developer workstation into its own integration platform.