Remote MCP connectors
Add Claude Desktop, ChatGPT, and Grok to the MCP server and finish OAuth in each host.
Remote MCP connectors
Claude Desktop, ChatGPT, and Grok each connect to one MCP resource on this
server. The host is the OAuth client. You enter the resource URL in the host,
the host discovers the authorization server, and the person using the host
signs in and approves consent. The host stores its own credential and calls
/mcp with it.
The embedded website assistant uses a different session. Adding a host here leaves that session alone.
Before opening a host, run MCP Connect. That command checks that this environment's MCP login works and prints the MCP URL, the issuer, and the scopes to type into the host. A successful run does not connect the host.
Addresses
Replace <api-host> with the public origin you already use for the API, with
no path and no trailing slash.
| Name | URL |
|---|---|
| MCP resource | https://<api-host>/mcp |
| Protected-resource metadata | https://<api-host>/.well-known/oauth-protected-resource/mcp |
| Authorization server (issuer) | https://<api-host>/api/auth |
| Authorization-server metadata | https://<api-host>/.well-known/oauth-authorization-server/api/auth |
| Host sign-in redirect | https://<api-host>/api/oauth/login |
| Consent | https://<api-host>/api/oauth/consent |
These are the defaults. A deployment can publish another issuer or resource.
Read authorization_servers from the protected-resource metadata and use that
issuer. The authorization-server metadata names the authorization, token, and
registration endpoints. Every host uses streamable HTTP.
Check the server before adding a host
-
Run the check in MCP Connect against this environment. When it fails, fix the server before anyone opens a host. When it succeeds, keep the printed URL, issuer, and scopes for the steps below.
-
Fetch the protected-resource metadata when you need to confirm the document the host will read.
resourceis the MCP URL,authorization_serverslists the issuer, andscopes_supportedis the public connection list:openid,profile,email,offline_access, and@read.curl -fsS "https://<api-host>/.well-known/oauth-protected-resource/mcp" -
Fetch the authorization-server metadata. A host can connect when
token_endpoint_auth_methods_supportedis exactlynone,grant_types_supportedis exactlyauthorization_codeandrefresh_token,code_challenge_methods_supportedincludesS256,scopes_supportedequals the public connection list, and aregistration_endpointis present while dynamic registration is allowed.curl -fsS "https://<api-host>/.well-known/oauth-authorization-server/api/auth"The same document is also served at
https://<api-host>/api/auth/.well-known/oauth-authorization-server. -
Registration creates the host's client. The server accepts a public client with
token_endpoint_auth_methodset tonone, theauthorization_codeandrefresh_tokengrants, response typecode, and the public connection scopes. The person does not type scopes or headers. After sign-in, the server enables the access that account already has. An operator can use factory tools and admin apps. A person without that access cannot. Registration rejects a client secret, a confidential token method,client_credentials, and the scopes@admin,@manage, and@write.When registration is turned off, the metadata has no usable registration endpoint and a registration attempt returns
invalid_client_metadatawith the descriptionDynamic client registration is disabled. Turn registration on for that deployment before asking a host to connect. The default is on.
Sign in when the host redirects you during authorization. Use the account
whose access should be exposed. The host shows the tools and apps that
account already has. Do not enter scopes or a privileged catalog. Claude
Desktop, ChatGPT, and grok.com do not need extra headers. Grok Build does.
The Grok Build section below sends the User-Agent header that its OAuth
discovery client omits.
Claude Desktop
- Open Claude Desktop settings and add a custom connector.
- Set the remote MCP URL to the MCP URL from the worksheet, normally
https://<api-host>/mcp. - Keep authentication on OAuth. Claude opens this server's sign-in and consent pages.
- Approve consent with the account whose tools and apps should be exposed.
- In a chat, enable the connector and ask Claude to list its tools.
Current Claude setup lives in account settings. This JSON records the URL for the person doing setup:
{
"mcpServers": {
"augeo": {
"type": "http",
"url": "https://<api-host>/mcp"
}
}
}Saving that fragment is a note. Claude still has to be pointed at the URL in account settings, and Claude still completes its own consent.
Anthropic documents the product path in Getting started with custom connectors using remote MCP.
ChatGPT
- Open the custom connector or developer-mode Apps flow. The label varies by version: Apps, then Create, or the account MCP form.
- Enter the MCP URL from the worksheet, normally
https://<api-host>/mcp. - Choose OAuth. When the form asks for an issuer, enter the issuer from the
worksheet, normally
https://<api-host>/api/auth. Leave scopes empty. The server advertises the public connection scopes, and the signed-in account determines which tools are enabled. - Complete this server's consent screen. ChatGPT stores the credential.
- In a conversation, confirm the connector lists tools.
OpenAI documents the product path in Developer mode and MCP apps in ChatGPT and Connect to ChatGPT.
Grok
Grok's servers call the MCP URL. Use the public HTTPS origin. Grok rejects a localhost name and a private address. The MCP Connect check rejects those addresses before it prints a worksheet.
- Open grok.com/connectors.
- Choose New Connector, then Custom.
- Enter the MCP URL from the worksheet, normally
https://<api-host>/mcp. - Save the connector. Grok runs OAuth and opens this server's sign-in and consent pages.
- In a conversation, confirm the connector's tools are listed.
Grok Business and Enterprise need an admin to add the connector before a member connects. The admin uses console.x.ai, then Grok Business, Connectors, Add Connector, Other. Members connect their own accounts at grok.com/connectors.
Use Custom MCP. A built-in catalog connector and the Responses API remote MCP tool are separate products.
xAI documents the product path in Grok connectors and connector management.
Grok Build
Grok Build is the local grok CLI. The grok.com steps above are a different
product. Grok Build also requires the public HTTPS origin from the worksheet.
It rejects a localhost name and a private address.
JSON-RPC calls from Grok Build send User-Agent: grok-cli/<version>.
OAuth discovery, client registration, and token requests use a second HTTP
client that sends no User-Agent. A client should send that header on each
request unless it is configured not to
(RFC 9110 section 10.1.5).
AWS WAF's core rule set
AWSManagedRulesCommonRuleSet
includes NoUserAgent_HEADER, and that rule's action is Block. Discovery
then receives 403, and Grok Build reports that the server does not support
OAuth. The same URL answers 401 when the request carries a User-Agent.
A headers entry on an HTTP MCP server, including User-Agent, reaches the
JSON-RPC client. It does not reach the discovery client, so leaving the
server on the url transport still fails behind that rule.
Connect through the npm package
mcp-remote. It adds the header
to every request, including discovery. Replace <api-host> with the origin
from the worksheet. Replace <version> with the version printed by
grok --version.
[mcp_servers.augeo]
command = "bunx"
args = [
"--bun",
"mcp-remote",
"https://<api-host>/mcp",
"--header",
"User-Agent: grok-cli/<version>",
"--transport",
"http-only",
]
enabled = trueWhen Bun is not installed, use npx and omit --bun:
[mcp_servers.augeo]
command = "npx"
args = [
"-y",
"mcp-remote",
"https://<api-host>/mcp",
"--header",
"User-Agent: grok-cli/<version>",
"--transport",
"http-only",
]
enabled = true- Run
grok mcp doctor augeo. A healthy server reports a handshake and a tool count. - In a session that is already open, open
/mcpsand pressrso it reloads the server list. - Finish the browser sign-in with the account whose tools should appear.
You can hand that setup to Grok Build. Replace <api-host> before you paste:
Add an MCP server named augeo to my user config at ~/.grok/config.toml.
Use a stdio command. Do not set a remote url for this server.
Read my installed version with `grok --version` and put that version in the
User-Agent. If `bunx` is on PATH, set command to the absolute bunx path and
args to: --bun, mcp-remote, https://<api-host>/mcp, --header,
User-Agent: grok-cli/<version>, --transport, http-only.
If bunx is missing, use npx -y mcp-remote with the same remaining arguments
and no --bun.
A headers.User-Agent value on an HTTP MCP server does not reach Grok's
OAuth discovery client. That client sends no User-Agent. RFC 9110 section
10.1.5 says a client should send one on each request. AWS WAF rule
NoUserAgent_HEADER in AWSManagedRulesCommonRuleSet blocks a request that
omits the header, and discovery then fails.
After the config is written, run `grok mcp doctor augeo` and report the
handshake and the tool count. If this session was already open, tell me to
open /mcps and press r. Leave the browser sign-in for me to finish.Confirm the connection
The host lists tools, and a tool call returns a result for the signed-in account. The account's grants decide which persona tools and MCP apps appear.
An unauthenticated initialize returns 401. The WWW-Authenticate header
carries resource_metadata set to the protected-resource metadata URL:
curl -sS -D - -o /dev/null -X POST "https://<api-host>/mcp" \
-H "content-type: application/json" \
-H "accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'Expect 401 and
resource_metadata="https://<api-host>/.well-known/oauth-protected-resource/mcp".
After a host has connected, it owns the MCP session:
POST /mcpsends a JSON-RPC message. The first request isinitializeand the response carriesMcp-Session-Id. Later requests include that header.GET /mcpopens the server-to-client event stream for that session.DELETE /mcpends the session and returns204.
An unknown session id returns 404. A first request that is something other
than initialize returns 400. A session belongs to the caller that created
it and expires after 30 minutes without use.
Related
- MCP Connect checks the environment and prints the worksheet.
- Getting started covers chat, threads, and calls that already have a bearer.