Guides

Connect an AI client

Let Claude, ChatGPT, VS Code, Cursor or any other MCP client work in one of your projects.

UnderOcean is an MCP server. Once connected, an AI client can list, create and update agents, flows and knowledge bases in one project, run them and search this documentation.

1. The endpoint

https://api.underocean.ai/mcp

Self-hosted installations use their Consumer API URL followed by /mcp. The endpoint speaks Streamable HTTP. Clients find the sign-in details on their own at /.well-known/oauth-protected-resource/mcp.

2. Add it to your client

Claude (web and desktop): Settings → Connectors → Add custom connector, paste the endpoint URL.

ChatGPT: add a custom connector (remote MCP server) and paste the endpoint URL.

VS Code: add the server to .vscode/mcp.json (workspace) or your user MCP configuration, then click Start above the entry:

{
  "servers": {
    "underocean": { "type": "http", "url": "https://api.underocean.ai/mcp" }
  }
}

Cursor: add it to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "underocean": { "url": "https://api.underocean.ai/mcp" }
  }
}

Other clients: use their "remote MCP server" or "custom connector" option with the same URL.

3. Approve the connection

The client opens the UnderOcean consent page in your browser. Sign in, then:

  1. Pick the project the client may work in. One connection covers exactly one project.
  2. Pick an access level: Read only, Read & execute, Builder (create and update) or Full access (Builder plus gates and deletes of documents). Builder and Full access are offered to self-registered apps only when your administrator has enabled it.
  3. Approve. The client receives its token and its tools appear.

The page marks the app as unverified because apps register themselves: only approve a connection you started. Connected apps are listed, and can be disconnected, under Settings → Connected apps.

Alternative: an API key

When a client cannot sign in through the browser, or you need Builder or Full access and they are not enabled for connected apps, create a key under Project → API Keys with the access level you need and send it as a bearer token. In VS Code the key can be asked for once and stored securely:

{
  "inputs": [
    { "id": "uo-key", "type": "promptString", "description": "UnderOcean API key", "password": true }
  ],
  "servers": {
    "underocean": {
      "type": "http",
      "url": "https://api.underocean.ai/mcp",
      "headers": { "Authorization": "Bearer ${input:uo-key}" }
    }
  }
}

Never commit a key into a configuration file. Keys from before scopes existed are not accepted on this endpoint.

4. Check the connection

Ask the client to list the agents in the project. If the call is refused, check the access level of the connection or key: clients only see the tools it allows.

What clients cannot do

  • Delete agents, flows, knowledge bases or other resources. The client gives you a link to the page where you delete it yourself.
  • Handle MCP server credentials. Servers are registered without them and you add them in the UI; provider listings never include keys or endpoints.
  • Manage gates, unless the connection (or API key) has Full access or the gates:* scopes.

On this page