HTTP MCP Servers

AllAgents acts as the MCP client for HTTP servers it manages. One command connects to the server, handles OAuth when required, saves the selected project, user, or profile declaration, and syncs every selected AI client:

allagents mcp add tradingview https://mcp.tradingview.com/mcp

You do not need to run a separate proxy or authentication command.

Add a Server

Use a stable name and the server’s HTTP endpoint:

allagents mcp add deepwiki https://mcp.deepwiki.com/mcp
allagents mcp add tradingview https://mcp.tradingview.com/mcp

For an HTTP server, mcp add:

1. Connects as the AllAgents MCP client
2. Opens a browser if the server requires OAuth
3. Verifies the MCP connection before changing the selected declaration
4. Stores the server under that destination’s mcpServers
5. Routes the selected AI clients through AllAgents and syncs their configs

Public servers such as DeepWiki complete without a browser. OAuth servers such as TradingView prompt for login on the first connection.

Local and Remote Browsers

The same command supports both environments:

• Local browser: approve access and let the browser return to the loopback callback. The terminal continues automatically.
• Remote or headless host: open the printed authorization URL on another device. After approval, copy the complete loopback callback URL from the browser address bar and paste it into the waiting terminal prompt.

AllAgents accepts only the registered loopback address with the exact OAuth state.

In a non-interactive shell, AllAgents still verifies the connection without opening a browser. Public servers and servers with valid cached credentials succeed. If fresh OAuth consent is required, the command fails before changing the workspace; rerun it in an interactive terminal.

Client Filters and Headers

allagents mcp add internal https://mcp.internal.corp \
  --header Authorization=Bearer-token \
  --client claude \
  --client codex,copilot

--client is repeatable and comma-compatible. It limits both server sync and AllAgents routing; duplicate values are ignored in first-seen order. Without --client, routing stays dynamic so clients added to the destination later receive the same AllAgents-managed connection. --header values are sent only to the MCP server origin, not to OAuth discovery or identity-provider origins.

Profile declarations accept only exact environment references for header values:

allagents mcp add tradingview https://mcp.tradingview.com/mcp \
  --profile markets \
  --header 'Authorization=${TRADINGVIEW_TOKEN}'

Generated profile bridge arguments store the header-to-variable binding, not the resolved secret. AllAgents resolves the variable immediately before the MCP connection and fails clearly when it is missing.

OAuth Client-Name Compatibility

Some OAuth servers accept dynamic registration only for recognized client names. AllAgents registers as AllAgents by default. Override the OAuth registration name for one HTTP server when the provider requires a compatible name:

allagents mcp add figma https://mcp.figma.com/mcp \
  --oauth-client-name 'Claude Code'

The declaration records the setting, so direct CLI calls and generated bridges use the same identity:

mcpServers:
  figma:
    url: https://mcp.figma.com/mcp
    oauth:
      clientName: Claude Code

Codex is another supported name value. This option changes OAuth client_name. The bridge forwards the connecting AI client’s MCP initialization identity and capabilities; direct AllAgents commands identify as AllAgents. It does not import another application’s tokens, client secret, or existing grant. It is not a guarantee that a provider will accept registration or grant access.

OAuth credentials are isolated by effective client name, server URL and profile. Changing the name requires fresh registration and consent; it does not reuse the previous identity’s tokens. After editing a declaration, run the matching mcp reauth command and sync the destination with mcp update so existing client bridges receive the setting. Removing the override selects the original AllAgents identity and its separate cache.

The setting is available in project, user and named-profile HTTP declarations. It is not valid for stdio servers. Every configured identity uses AllAgents’ bridge, including Pi, so registration, reauthentication and token reuse share the same identity-isolated cache. Without an override, native HTTP routing is unchanged.

URL query values may be exact ${ENV_VAR} references. AllAgents resolves them from the connection environment, not while generating client configuration. Missing variables fail before connecting. Partial references and references in the URL host or path are not supported.

Figma registration probes accepted both Claude Code and Codex, while the default AllAgents name was rejected. Those probes stopped before consent; registration success alone does not establish authenticated tool access.

Reauthenticate

Use the configured server name, not its URL:

allagents mcp reauth tradingview
allagents mcp reauth tradingview --scope user
allagents mcp reauth tradingview --profile markets

reauth clears only the selected destination’s cached OAuth registration and tokens, then runs a fresh connection and login. It does not revoke the grant at the remote provider. Reconnect the AI client afterward if it already had an MCP session open.

Use a Server from the CLI

Runtime discovery and calls reuse the same project, ordinary user, or named profile declarations managed by mcp add:

allagents mcp tools tradingview
allagents mcp call tradingview quote --symbol AAPL
allagents mcp tools tradingview --scope user
allagents mcp call tradingview quote --profile markets --symbol AAPL
allagents mcp probe tradingview --profile markets

Unlike an external AI client, mcp tools, fully qualified mcp call ... --help, and mcp call connect directly to the configured HTTP endpoint. They do not go through the generated client bridge. They still use the same credential ownership: project and ordinary user declarations use the ordinary URL-keyed cache, while each profile has its own isolated cache. Valid cached credentials are reused and expired access tokens are refreshed when possible.

Runtime commands do not open a browser or request fresh OAuth consent. If the cached grant cannot authorize the connection, the error prints the exact destination-specific mcp reauth command to run interactively. After that succeeds, rerun the discovery, help, or call command.

For a stdio declaration, runtime discovery, live help, and calls start the configured process directly with its configured arguments and environment. Treat a configured stdio command as executable code you trust.

mcp probe checks the connection, lists tools and advertised resources, and closes the session before printing. It shares the runtime commands’ credentials and never starts fresh human consent.

Connection Options

HTTP declarations support a connection object. Settings apply to both direct commands and generated bridges:

mcpServers:
  internal:
    url: https://mcp.example.com/mcp
    connection:
      transportStrategy: http-first
      ignoreTools: ["delete*", "remove*"]
      keepAliveSeconds: 30
      bodyTimeoutSeconds: 0

Setting	Behavior
transportStrategy	http-first (default), sse-first, http-only, or sse-only. An initial 404 or 405 tries the alternative transport once when using a fallback strategy. Both try the configured URL without rewriting its path.
ignoreTools	Case-insensitive patterns with * wildcards. Excluded tools disappear from discovery and direct calls are rejected.
keepAliveSeconds	Periodic pings on legacy connections. Modern notification subscriptions manage their own liveness.
connectTimeoutSeconds	Timeout for establishing an outbound connection.
headersTimeoutSeconds	Timeout for waiting for response headers. Zero disables it.
bodyTimeoutSeconds	Maximum gap between incoming chunks, rather than a total stream lifetime. Zero disables it.
protocol: auto	Probe for the 2026-07-28 protocol and bridge compatible older hosts. Default legacy sends the original handshake without a probe.
enableProxy: true	Use HTTP_PROXY, HTTPS_PROXY, and NO_PROXY for MCP and OAuth requests.
ipv4: true	Open outbound connections over IPv4.
disableCookies: true	Disable the default in-memory sticky-session cookies. Cookies otherwise stay within their exact response origin and matching paths, respect Secure, and preserve distinct sessions on different paths. Explicit Cookie headers take precedence.
debug: true	Write connection diagnostics beneath ~/.allagents/mcp-debug/ and print their location to stderr. Diagnostics omit credentials and raw protocol payloads.
silent: true	Suppress ordinary bridge diagnostics. Explicit debug output remains enabled.

Transport fallback is limited to startup. An established tool request’s error does not switch transports or replay the request on another transport. Node’s NODE_EXTRA_CA_CERTS environment variable supplies additional trusted certificate authorities without disabling certificate verification.

Registered Clients and Grants

Use a registered client when the provider does not permit dynamic registration:

mcpServers:
  internal:
    url: https://mcp.example.com/mcp
    oauth:
      clientId: team-client
      clientSecret: ${MCP_CLIENT_SECRET}
      scope: read write

Profiles require exact environment references for clientSecret and credential authorization parameters such as api_key. Public parameters such as audience can remain literal values. Generated bridges retain that binding rather than putting the resolved secret in process arguments. Changing identity-bearing registration or authorization settings selects a separate credential cache. Resource headers also participate in the cache identity, so separate tenant headers cannot share a grant.

Other oauth settings are:

Setting	Behavior
clientMetadata	Standard registration metadata, including software identification and token endpoint authentication method.
clientMetadataUrl	A client metadata document for providers that support it. Configure its registered callback port.
issuer	Bind a registered client to one authorization-server issuer. Credentials are refused when discovery selects a different issuer.
resource	Explicit resource indicator for authorization, token exchange and refresh.
authorizationParams	Extra authorization parameters such as audience, prompt, or access_type. Flow-owned parameters such as state and code_challenge cannot be replaced. Values are included in the browser authorization URL during consent.
disableResourceParameter	Omit the resource indicator when true.
grantType	authorization_code (default), device_code, or client_credentials.
tokenEndpoint	Explicit endpoint that skips discovery, valid only for client credentials.
allowHttp	Permit an HTTP token endpoint or callback success destination on a trusted private network. Without it these destinations require HTTPS or HTTP loopback.
useIdToken	Use the provider’s ID token for bearer authentication and its expiry for renewal. The provider must issue an ID token.

Device authorization prints a verification URL and user code and waits for approval without a local browser or callback port. Runtime commands can refresh an existing device grant but do not request fresh consent. Client credentials use the configured client ID and secret without a human login.

oauth.callback supports port, host, bindHost, path, timeoutSeconds, and successUrl. host is the advertised redirect host; bindHost is the listen address. Defaults retain AllAgents’ loopback callback. An explicit port is used exactly, rather than silently moving a registered redirect URI. The success destination is used only after token exchange and receives no code, state or token parameters.

Options from the CLI

allagents mcp add internal https://mcp.example.com/mcp \
  --connection-config '{"transportStrategy":"http-only","ignoreTools":["delete*"]}' \
  --oauth-config @oauth-options.json \
  --header-file headers.txt

Both option arguments accept a JSON object or @path/to/file.json. --header-file accepts one Name: value per line, ignoring blank and # comment lines. Unreadable files fail before mutation. Explicit --header values take precedence. Ordinary header values can include environment references; profiles retain their exact-reference requirement. Resource headers remain restricted to the MCP origin and are never forwarded to a separate OAuth identity provider.

Protocol Forwarding

The bridge forwards requests, responses, errors and notifications in both directions. It preserves host capabilities and remote metadata, including roots, sampling, elicitation, resource subscriptions, progress, cancellation, logging and task-shaped results.

With connection.protocol: auto, modern servers are discovered once, compatible legacy initialization is answered locally, and per-request protocol metadata is carried upstream. Notification subscriptions and supported input requests are translated for the connecting host. A request the host has not declared it can answer fails explicitly. Default legacy connections retain the original handshake.

Concurrent bridge processes coordinate registration, consent and rotating-token refresh within the selected scope. Owner failure permits recovery without sharing grants across identities or profiles.

Compatibility Baseline

The connection options above target the published mcp-remote@0.16.5 capabilities. AllAgents keeps its own setup, destination selection, credential cache and recovery commands. Option names follow the YAML policy rather than upstream’s command-line spelling.

Upstream capability	AllAgents equivalent
HTTP/SSE strategy and bidirectional stdio bridge	connection.transportStrategy; generated mcp proxy bridge
Modern protocol translation	connection.protocol: auto
Static registration, metadata, scopes, resource and authorization parameters	oauth settings above
Device and client credentials grants, explicit token endpoint and ID-token bearer	oauth.grantType, tokenEndpoint, useIdToken
Callback address, deadline and completion destination	oauth.callback
Shared login and rotating refresh coordination	Automatic within each destination and credential identity
Tool exclusions and keep-alive	connection.ignoreTools, keepAliveSeconds
Proxy, custom trust roots, timeouts and IPv4	connection settings and NODE_EXTRA_CA_CERTS
Sticky-session cookies	Automatic exact-origin cookie jar; disableCookies opts out
Header files and environment substitution	--header-file, --header-env, YAML header references
Debug and silent output	connection.debug, silent
Diagnostic client	mcp probe, mcp tools, mcp call

Protocol and authorization behavior is covered with local HTTP, SSE and OAuth fixtures. Modern translation is opt-in and tested against a local modern-only server. These checks do not establish compatibility with every live provider or native AI-client release.

Stdio Servers

Stdio servers use the same add command and run directly rather than through the HTTP client:

allagents mcp add gh-server npx \
  --arg=-y \
  --arg=@modelcontextprotocol/server-github \
  -e GH_TOKEN=ghp_xxx

How AI Client Routing Works

AI clients have different MCP transport support. AllAgents normalizes that difference: HTTP servers added with mcp add are synced as stdio commands that launch AllAgents’ internal HTTP bridge. OAuth registration and tokens are therefore shared instead of being configured independently in every client.

Generated AI-client configs invoke a version-pinned internal bridge. That bridge looks up the same destination declaration and credential cache, which lets clients in one destination share OAuth state instead of configuring credentials independently. A named profile’s generated bridge remains bound to that profile-owned cache and cannot share credentials with another profile.

The bridge is generated plumbing, not a user-facing command. AllAgents pins the package version that created the config, and npx reuses npm’s package cache on later launches. Use mcp tools or mcp call for direct CLI runtime access and mcp reauth when fresh consent is required.

Plugin-Provided Servers

Servers declared by plugins are not added through mcp add. To route those through AllAgents, use the advanced destination-local mcpProxy setting:

mcpProxy:
  clients:
    - codex
  servers:
    plugin-server:
      proxy:
        - claude
        - copilot

The optional clients list applies to every HTTP server in that destination. Per-server lists add clients for only the named server, and * selects every eligible client. Profiles place the same shape beside their own mcpServers under profiles.<name>.mcpProxy; profile policy never uses qualified global client IDs. Stdio servers are never transformed.

OAuth Cache

AllAgents caches OAuth client registration, tokens, PKCE verifier, and discovery metadata per server URL. Project and ordinary user declarations share the ordinary cache:

~/.allagents/oauth-proxy/<hash-of-server-url>/

Each named profile owns an isolated cache:

~/.allagents/profiles/<profile>/oauth-proxy/<hash-of-server-url>/

Both contain client-info.json, tokens.json, code-verifier.txt, and discovery.json. Clients inside one profile share those files; different profiles do not. Later connections reuse valid tokens and refresh expired access tokens when possible. mcp reauth --profile <name> resets only that profile.

These paths describe the default AllAgents identity. Explicit compatibility names use separate caches beneath the corresponding URL/profile scope. mcp reauth resets only the effective identity selected by the declaration; it does not clear or borrow another identity’s credentials. Rotating a secret referenced in a URL query does not select a new OAuth cache; the authored URL remains its identity. Changing a tenant header selects a separate grant. A declaration with headers may need one new sign-in when upgrading from a version that did not partition its cache by headers.

Removing an installed or declared-only profile removes its OAuth subtree with its other profile-owned runtime state. Cleanup rejects symbolic-link or non-directory OAuth roots and retains retryable state on failure.

Prerequisites

The generated bridge requires Node.js with npx available. A global AllAgents installation is not required: both setup and the generated MCP connection can use the npm cache.

The first bridge launch downloads the pinned AllAgents package if that version is not already cached. Later launches reuse the cached package. Environments that must work offline should prime the cache before disconnecting.

Destinations

HTTP MCP routing supports project, ordinary user, and named profile destinations. Omit destination flags for project scope, use --scope user for ordinary user configuration, or --profile <name> for a profile. --scope and --profile cannot be combined. From the home directory, the project path aliases the user workspace, so an unflagged command resolves to user scope and explicit --scope project is rejected.

Destination	Codex	Copilot
Project	.codex/config.toml	.github/mcp.json
User	~/.codex/config.toml	~/.copilot/mcp-config.json
Profile	~/.allagents/profiles/<name>/clients/codex/home/<name>.config.toml	~/.allagents/profiles/<name>/clients/copilot/home/mcp-config.json

Project and ordinary user updates are MCP-only. Updating an installed profile uses the ownership-aware profile reconciler because some clients combine MCP and settings in one file. Editing a declared but uninstalled profile does not implicitly install it.