Register a Shared MCP Client
A shared MCP client lets every user in your application call an external MCP server through one set of credentials. The application authenticates on behalf of users with a single identity managed by administrators. Use a shared client for service tokens, shared API keys, or any MCP server that does not need to know which human user is calling.
To register a per-user OAuth identity instead, see Connect a User to an MCP Server.
Before you begin
You need:
- Permission to write APP, ENV, or CLUSTER level config on the target application. Shared client credentials live at one of those scopes and are stored as a secret on GenaiCore.Mcp.Client.Shared.Config.
- The MCP server's base URL.
- The auth headers the MCP server expects on every request (for example,
Authorization: Bearer <service-token>or a vendor-specific API key header). - A name for the new client. The name must be unique within the application.
Register the client
Call GenaiCore.Mcp.Client.Shared's register method with the name, URL, and a GenaiCore.Mcp.Client.Shared.RegisterSpec carrying the auth headers.
spec = c3.GenaiCore.Mcp.Client.Shared.RegisterSpec(
headers={"Authorization": "Bearer <service-token>"},
failIfExists=True,
override="APP",
)
client = c3.GenaiCore.Mcp.Client.Shared.register(
name="weather-mcp",
url="https://mcp.example.com/weather",
spec=spec,
)After the call returns, the client is persisted and reachable by name from any application context:
client = c3.GenaiCore.Mcp.Client.Shared.forName("weather-mcp")
tools = client.listTools()RegisterSpec fields
| Field | Type | Purpose |
|---|---|---|
headers | map<string, string | [string]> | Auth headers sent on every request to the MCP server. Stored as a secret on GenaiCore.Mcp.Client.Shared.Config. |
failIfExists | boolean | Set to true to raise an error if a client with the same name already exists. If false or omitted, the call upserts. |
override | string enum ConfigOverride | The override level to write credentials to: APP, ENV, or CLUSTER. If omitted, C3 auto-selects based on the current app context. |
The base GenaiCore.Mcp.Client.RegisterSpec defines these fields; GenaiCore.Mcp.Client.Shared.RegisterSpec inherits them without adding any of its own.
Where credentials live
Shared headers are stored on GenaiCore.Mcp.Client.Shared.Config, which is annotated @config(secret=true) on the headers field. The config's minOverride is APP, so the same credentials apply to every user within the chosen override scope.
Rotate credentials
To rotate the credentials, call register again with the same name and the new headers. Leave failIfExists unset (or set to false) so the call upserts the existing client.
spec = c3.GenaiCore.Mcp.Client.Shared.RegisterSpec(
headers={"Authorization": "Bearer <new-service-token>"},
override="APP",
)
c3.GenaiCore.Mcp.Client.Shared.register(
name="weather-mcp",
url="https://mcp.example.com/weather",
spec=spec,
)