Skip to main content

Connect ChatGPT to AgentDock

OAuth is recommended when ChatGPT connects to a remote AgentDock instance through a custom MCP plugin. During connection, ChatGPT discovers AgentDock's OAuth metadata, registers a client, and completes browser authorization automatically. You do not need to create a Client ID or Client Secret manually.

AgentDock currently supports OAuth 2.0 Authorization Code, PKCE S256, dynamic client registration, and Refresh Tokens.

Prerequisites​

Before you begin, confirm that:

  • AgentDock is deployed at a public URL that ChatGPT can reach.
  • The public endpoint uses a valid HTTPS certificate.
  • The MCP URL ends with /mcp, for example https://agentdock.example.com/mcp.
  • The reverse proxy forwards /mcp, /register, /oauth/*, and /.well-known/* without rewriting them incorrectly.
warning

Do not enter a loopback URL such as http://127.0.0.1:8765/mcp in ChatGPT. ChatGPT cannot reach a loopback address on your computer or server.

1. Enable OAuth​

Add these values to the AgentDock environment file, Docker Compose environment, or service environment:

AGENTDOCK_OAUTH_ENABLED=true
AGENTDOCK_SERVER_URL=https://agentdock.example.com
AGENTDOCK_OAUTH_PASSWORD=<password-used-for-connection-authorization>
AGENTDOCK_OAUTH_TOKEN_SECRET=<random-signing-key-at-least-32-bytes>

Generate random values with OpenSSL:

openssl rand -base64 24   # Suitable for the authorization password
openssl rand -hex 32      # Suitable for the token signing key

Requirements:

  • AGENTDOCK_SERVER_URL contains only the origin, without /mcp, another path, query parameters, or a fragment.
  • A public URL must use https://.
  • AGENTDOCK_OAUTH_PASSWORD must contain at least 12 characters.
  • AGENTDOCK_OAUTH_TOKEN_SECRET must contain at least 32 bytes and remain stable across restarts.

You may omit AGENTDOCK_AUTH_TOKEN when OAuth is the only authentication method. Both methods can also be enabled together for different MCP clients.

Restart AgentDock after changing the configuration. For systemd:

sudo systemctl restart agentdock
sudo systemctl status agentdock --no-pager

For Docker Compose:

docker compose up -d

2. Verify the OAuth endpoints​

First verify the health endpoint and OAuth metadata:

curl -fsS https://agentdock.example.com/healthz
curl -fsS https://agentdock.example.com/.well-known/oauth-authorization-server
curl -fsS https://agentdock.example.com/.well-known/oauth-protected-resource/mcp

The second request should return JSON containing these endpoints:

authorization_endpoint  https://agentdock.example.com/oauth/authorize
token_endpoint          https://agentdock.example.com/oauth/token
registration_endpoint   https://agentdock.example.com/register

Do not open /oauth/authorize manually. It requires the client, callback URL, and PKCE parameters generated by ChatGPT, so a direct request normally returns a parameter error.

3. Create the plugin in ChatGPT​

  1. Open ChatGPT and go to Settings > Plugins > Advanced settings.

  2. Enable Developer mode.

  3. Select Create plugin.

  4. Use AgentDock as the plugin name.

  5. Enter this MCP Server URL:

    https://agentdock.example.com/mcp

  6. Save the plugin and begin the connection. Choose OAuth authentication, or let ChatGPT discover it from the server metadata.

  7. When the browser opens the AgentDock authorization page, confirm that the plugin name and callback domain belong to the connection you just started.

  8. Enter AGENTDOCK_OAUTH_PASSWORD and select “Verify and connect.”

  9. After the browser returns to ChatGPT, confirm that the plugin is available.

ChatGPT obtains a Client ID from AgentDock's dynamic registration endpoint. You do not need to enter a Client ID, Client Secret, authorization URL, or token URL manually.

4. Complete a real verification​

Start a new ChatGPT conversation and try:

Use AgentDock to inspect the current device.

A read-only verification is also suitable:

Call AgentDock's server_info and tell me the service version, operating system, and current authentication mode.

Do not treat the OAuth redirect alone as proof of success. Confirm that ChatGPT can list AgentDock tools and complete a real tool call.

Troubleshooting​

The authorization page does not open​

Check, in order:

  • The MCP URL ends exactly with /mcp.
  • AGENTDOCK_OAUTH_ENABLED is true.
  • AGENTDOCK_SERVER_URL exactly matches the HTTPS origin used in the browser.
  • /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp are reachable from the public internet.
  • The reverse proxy allows /register, /oauth/authorize, and /oauth/token.

The page keeps loading after authorization​

A successful POST /oauth/authorize returns a 302 redirect to ChatGPT's callback. The 302 is expected. If the browser does not continue, inspect the reverse proxy, browser console, and the response Location header for rewriting or blocking.

The password is rejected​

Enter AGENTDOCK_OAUTH_PASSWORD, not the Bearer Token or AGENTDOCK_OAUTH_TOKEN_SECRET. Repeated failures trigger a short rate limit.

Connection still fails after configuration changes​

Restart AgentDock and verify the three public endpoints again. Then remove the old plugin from ChatGPT and create it again so the client does not keep stale registration or authorization state.

Security recommendations​

  • Use a dedicated domain and a valid HTTPS certificate for AgentDock.
  • Keep the authorization password and token signing key in a permission-restricted environment file or secret manager.
  • Never publish real passwords or signing keys in a README, Compose file, chat, or screenshot.
  • Do not log Authorization headers, OAuth codes, or request bodies at the reverse proxy.
  • AgentDock operates real resources with its process or container permissions. Grant only the directories and commands required for the task.

See Configuration for all environment variables and Manual Linux deployment for a public deployment.