Concepts

MCP (Model Context Protocol)

Connecting agents to external tools and services via an open integration standard.

UnderOcean integrates the Model Context Protocol (MCP) — an open standard for connecting AI agents to external tools, data sources, and services (filesystems, GitHub, Slack, databases, and custom servers).

Per-project integrations

Each project manages its own set of connected integrations:

  • A list of connected servers, configured by URL or launch command
  • The tools each one exposes, discovered automatically
  • Which tools are assigned to which agents
  • Connection health/status, with an on-demand test that names the reason when it fails (HTTP status, rejected credentials, no answer in 15 seconds)

Registering a server

  • Remote servers (SSE or Streamable HTTP, the default) need a url; the URL must be a public https address and must not contain credentials (user:password@host). Put API keys and tokens in Extra Headers, e.g. Authorization.
  • Extra headers must be valid HTTP header names, can't repeat (names are case-insensitive) and can't override headers the client owns (Host, Content-Length, Transfer-Encoding, Connection and similar).
  • Names are unique within a project, ignoring case: they prefix the tool names the model sees (<server>__<tool>, accents folded, at most 64 characters).
  • View tools and Test use the same 15-second limit; a failure comes back as a 424 with the reason, not a bare gateway error. Tool calls time out after 60 seconds.
  • Deleting a server removes it from every agent that used it, right away. Flows whose MCP Tool node points at it refuse to run (naming the node) until you pick another server.

Using tools in agents and flows

  • An agent can be assigned a set of tools directly, which the model may call during a single-agent execution. A bound server that can't be reached is reported as a step of the run (and stored with it) instead of being skipped silently. The stored run (GET /v1/executions/{id}) lists each tool call and observation under reasoning.steps.
  • A flow's tool-call step invokes a specific tool on a specific integration as one step in a larger workflow, so its output can be branched on, aggregated, or passed to another agent.

UnderOcean as an MCP server

UnderOcean also is an MCP server, so AI clients such as Claude or ChatGPT can work in one of your projects. The endpoint is /mcp on the Consumer API host (Streamable HTTP, stateless). It works on exactly one project and offers tools to list, read, create and update agents, flows and knowledge bases, run agents and flows, search knowledge bases, list the LLM, embedding, text-to-speech and speech-to-text providers (and the voices of a text-to-speech provider) an agent, knowledge base, flow or voice gate can use, register remote MCP servers, and search this documentation (search_docs). Flow graphs are edited with flow_apply_operations, including the voice nodes.

Skills. The server sends short usage instructions when a client connects and offers task guides (flow-building, agent-setup, knowledge-base, mcp-servers, gates-widgets, voice, executions-debugging, verbatim-input) through the list_skills and load_skill tools, and as MCP prompts and skill:// resources. AI clients should load the matching guide before a task and copy the values you give them exactly. Nothing but documents can be deleted, and secrets never pass through a tool: MCP servers are registered without credentials, which you add in the UI, and provider listings never include keys or endpoints.

Connecting an app. Add the endpoint as a custom connector in the client (step by step for each client: Connect an AI client). It discovers our OAuth server, registers itself, and sends you to the consent page: pick the project and an access level (Read only or Read & execute; Builder and Full access only when your administrator has enabled write access for self-registered apps). Because apps register themselves, the consent page marks them as unverified: only continue if you started the connection. Apps you connected are listed, and can be disconnected, under Settings → Connected apps. Platform administrators cannot connect apps. Alternatively, authenticate with an API key that has MCP-capable scopes; legacy full-access keys are not accepted.

Access levelTools it unlocks
Read onlyEverything that lists or reads: agents, flows, their version histories, flow node types, knowledge bases, documents and chunks, MCP servers, LLM, embedding and speech providers, past runs and conversations (sessions), usage and cost reports, and documentation search
Read & executeRead only, plus knowledge-base search, running and cancelling agents and flows, and uploading files to send with a run (attachments:write)
BuilderRead & execute, plus creating and updating agents, flows, knowledge bases (settings, text documents, chunks, graph index) and MCP servers, and restoring earlier versions
Full accessBuilder, plus managing gates (listing, creating and updating channel connections, placing outbound calls), deleting documents and every other Consumer API scope (providers, settings)

Full access is never given to the assistant. Grant it to a connected app only when you want that app to manage your public channels too.

Deleting a document needs the knowledge:delete scope (Full access, or an API key with that scope). Nothing else can be deleted through a tool: when you ask a client to delete an agent, flow, knowledge base, gate, MCP server, provider, carrier, API key or project, it calls get_delete_link and gives you the exact link to the page where you delete it, with the row and button to use. Managing gates needs the gates:* scopes, which only Full access (or an API key created with those scopes) holds. Clients only see the tools their credential allows.

What a client can do is always the intersection of the access level you granted and what you can do yourself in that project right now: if your role or project access is reduced, the connected app loses it immediately. Every change made through MCP is recorded in the project's audit trail with the app (or key) and the person behind it, and shows up in the resource's version history as made through MCP. Tools are annotated read-only, destructive or idempotent so clients can ask for confirmation appropriately.

Working with the tools. List tools return compact summaries and the matching get_* tool returns the full object; list_agents and list_flows take limit (1-200, default 50) and offset to page through large projects. Updates take the expected_revision from the last read, so a stale edit is rejected with a revision_conflict instead of overwriting newer work; an update (or version restore) that omits it is refused with revision_required (a flow dry_run is exempt). execute_agent and execute_flow return a session_id: pass it on the next call to continue the same conversation, or omit it to start a new one. Errors come back as a structured { error: { code, message } } result and are never silently repaired: invalid arguments report each offending field. execute_agent and execute_flow require input (for an agent, {"message": "..."}); a missing or empty message is refused before any model call. create_flow and update_flow describe graph_definition as {nodes, edges}; create_flow returns what still blocks an unfinished graph (for example no Output node) in validation_warnings, and such a flow can't be run until it is fixed. Calls are rate-limited per credential in three tiers (read, write, execute) and report a 429 error when exceeded, and browser-based clients must call from an origin the deployment allows.

The in-app assistant

The AI Assistant panel inside a project uses these same tools to build and operate things for you in plain language, with every change shown for approval first. It has its own page: AI Assistant.

On this page