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 publichttpsaddress 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,Connectionand 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
424with 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 underreasoning.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 level | Tools it unlocks |
|---|---|
| Read only | Everything 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 & execute | Read only, plus knowledge-base search, running and cancelling agents and flows, and uploading files to send with a run (attachments:write) |
| Builder | Read & execute, plus creating and updating agents, flows, knowledge bases (settings, text documents, chunks, graph index) and MCP servers, and restoring earlier versions |
| Full access | Builder, 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.