Augeo AI Docs
AI Server

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.

NameURL
MCP resourcehttps://<api-host>/mcp
Protected-resource metadatahttps://<api-host>/.well-known/oauth-protected-resource/mcp
Authorization server (issuer)https://<api-host>/api/auth
Authorization-server metadatahttps://<api-host>/.well-known/oauth-authorization-server/api/auth
Host sign-in redirecthttps://<api-host>/api/oauth/login
Consenthttps://<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

  1. 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.

  2. Fetch the protected-resource metadata when you need to confirm the document the host will read. resource is the MCP URL, authorization_servers lists the issuer, and scopes_supported is the public connection list: openid, profile, email, offline_access, and @read.

    curl -fsS "https://<api-host>/.well-known/oauth-protected-resource/mcp"
  3. Fetch the authorization-server metadata. A host can connect when token_endpoint_auth_methods_supported is exactly none, grant_types_supported is exactly authorization_code and refresh_token, code_challenge_methods_supported includes S256, scopes_supported equals the public connection list, and a registration_endpoint is 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.

  4. Registration creates the host's client. The server accepts a public client with token_endpoint_auth_method set to none, the authorization_code and refresh_token grants, response type code, 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_metadata with the description Dynamic 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

  1. Open Claude Desktop settings and add a custom connector.
  2. Set the remote MCP URL to the MCP URL from the worksheet, normally https://<api-host>/mcp.
  3. Keep authentication on OAuth. Claude opens this server's sign-in and consent pages.
  4. Approve consent with the account whose tools and apps should be exposed.
  5. 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

  1. Open the custom connector or developer-mode Apps flow. The label varies by version: Apps, then Create, or the account MCP form.
  2. Enter the MCP URL from the worksheet, normally https://<api-host>/mcp.
  3. 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.
  4. Complete this server's consent screen. ChatGPT stores the credential.
  5. 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.

  1. Open grok.com/connectors.
  2. Choose New Connector, then Custom.
  3. Enter the MCP URL from the worksheet, normally https://<api-host>/mcp.
  4. Save the connector. Grok runs OAuth and opens this server's sign-in and consent pages.
  5. 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 = true

When 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
  1. Run grok mcp doctor augeo. A healthy server reports a handshake and a tool count.
  2. In a session that is already open, open /mcps and press r so it reloads the server list.
  3. 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 /mcp sends a JSON-RPC message. The first request is initialize and the response carries Mcp-Session-Id. Later requests include that header.
  • GET /mcp opens the server-to-client event stream for that session.
  • DELETE /mcp ends the session and returns 204.

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.

  • MCP Connect checks the environment and prints the worksheet.
  • Getting started covers chat, threads, and calls that already have a bearer.