Skip to main content
MCP configuration and credentials have separate stores. Definitions describe the endpoint and OAuth application; credentials hold each namespace’s account grant. Share the stores and credential provider between agent execution and HTTP management.

​
Persist definitions

The file is a JSON array of ServerConfig values. An empty namespace means global; a user record belongs to one namespace. File stores reload on listing and atomically replace their file on writes. Use a transactional custom store for concurrent writes across processes. NewStore(customStore) adds inline configuration views to a custom store. Pass client to AgentConfig.MCPClient. For the embedded UI, pass agui.WithMCPStore(store) to web.Handler and configure its namespace resolver. Management routes use the authenticated namespace; clients cannot choose another one in a request body.

​
Connect OAuth accounts

Import pkg/agents/mcpclient. This example assumes the remote server supports authorization discovery and dynamic client registration:
Replace the endpoint and callback with your server and deployment. Supply ClientID and ClientSecret when using a registered application. For servers without discovery, also provide AuthURL and TokenURL; explicitly configured endpoints require a client ID. Mount the same provider using agui.WithMCPStore(store, mcpclient.WithOAuth(provider)). Visiting /api/agui/mcp/notes/connect starts authorization. The callback checks browser-bound state and PKCE, then stores refreshable credentials. Missing credentials are reported as authentication status during discovery.

​
Management routes

The following paths are relative to the embedded UI’s /api/agui prefix: Global and inline definitions are read-only. A user definition can contain literal headers or its own OAuth settings, but cannot contain templates, stdio commands, environment variables, or UseCredentials. Public-address checks apply when connecting, including DNS results and redirects. Trusted global definitions may use internal services. A standalone handler is mcpclient.NewHandler(store, mcpclient.WithNamespaceResolver(resolve), mcpclient.WithOAuth(provider)); mount it with http.StripPrefix. Without a trusted namespace resolver it denies requests.

​
Deployment

The file credential store contains plaintext tokens in private files. Protect its directory. Share one provider in a process to coordinate refreshes. Multi-process deployments need persistence and refresh coordination suitable for concurrent token rotation. OAuth state is process-local and expires after ten minutes, so connect and callback must reach the same handler instance. Register the complete callback URL and keep credentials available until all requests and workers finish. Changing the definition’s OAuth client or token endpoint can require reconnection.