Is It Possible to Access Multiple Teams mcp resource with One MCP URL and One Token?

[xqdd]

For permission control, I treat a "team" as a "role" and assign multiple teams to a user. However, from the user's perspective, they have to configure multiple virtual MCP URLs and API tokens for agents such as Codex and Claude Code.

Is there any way to use a single MCP URL and a single token to access resources across multiple teams?

[crivetimihai]

Hi @xqdd, great question.

Yes, a single JWT token can contain multiple teams in the teams claim:

{
  "teams": ["team-alpha", "team-beta", "team-gamma"],
  "is_admin": false,
  "token_use": "api"
}

normalize_token_teams() normalizes this list, and the visibility filter uses team_id.in_(token_teams) — so a user whose token lists multiple teams can see tools/resources from all those teams.

However, there are two important constraints:

1. Each virtual server has a single team_id — the Server model has a singular team_id field, not a list. So each virtual server URL only exposes one team's tools/resources.

2. Team membership is validated against the database — the gateway checks that the teams listed in your JWT actually exist in the DB and that the user is a member. If the teams don't exist or the user isn't a member, the request is rejected with 403 ("User is no longer a member of the associated team").

For your use case (teams as roles):

You need one virtual server URL per team. The user needs multiple MCP URLs but can use one token containing all their teams. The flow would be:

1. Create teams in ContextForge (via Admin UI or API)
2. Assign tools to the appropriate teams
3. Create one virtual server per team, each with its team_id set
4. Generate one API token for the user with teams: ["team-a", "team-b", ...]
5. The user configures one MCP URL per virtual server, all using the same token

What's not possible today: A single virtual server that aggregates tools from multiple teams. Each server is scoped to one team (or null for public). If you want a unified endpoint exposing tools from multiple teams, the closest option is a public virtual server with visibility: "public" on the tools — but that bypasses team isolation entirely.

Related: There's a known bug (#3654) where Admin API tokens created with "All Teams" selected get teams: [] instead of teams: null, which blocks admin access. This is being tracked and fixed.

Would creating one virtual server per team (with one shared token) work for your use case, or do you specifically need a single-URL solution?

[omni-front]

not sure about this one tbh. might be best to dive into the MCP docs or check with IBM support.

[itxashancode]

If your auth middleware checks the teams claim against the resource's required team(s), yes - you can use a single token with all teams and one MCP URL. The token's teams array should include every team the user needs

[omni-front]

ah good catch, you're right. thanks for the clarification!

[itxashancode]

❤️