Skip to main content
Most teams install connectors from the platform catalog (Gmail, Postgres, GitHub, and 40+ Go adapters). When you operate your own Model Context Protocol server — internal tools, a partner API wrapper, or a locally hosted adapter — register it as a workspace-owned MCP server and add an instance like any other connector.

​
Platform vs custom

Custom servers create an mcp_servers row scoped to your workspace. You still wire connections on Instance config profiles when tools need credentials.

​
Requirements

Your MCP server must:
  • Speak MCP over HTTP at a stable URL (for example https://tools.example.com/mcp)
  • Expose tools with JSON input and output schemas
  • Be reachable from AgentRuntime’s runtime network (public HTTPS or allowlisted private endpoint)
  • Return at least one tool on discover — empty catalogs fail registration
For greenfield servers, the AgentRuntime MCP SDK packages (agentruntime-mcp for Python, agentruntime-mcp-go for Go) provide router helpers compatible with platform discovery.
Custom MCP registration is not the same as Platform MCP (mcp.agentruntime.io) for IDE automation. Platform MCP wraps Console REST APIs. Custom servers are project tool servers for workflow mcp_call steps.

​
Register in the Console

1

Open MCP connectors

Go to MCP (/mcp) and click Add connectors.
2

Add connector

In the marketplace modal, click Add connector (not Add instance on a platform row). This opens the registration wizard.
3

Register server

Enter Name, Server URL (canonical_url), and optional Description. Click Register →.
4

Discover tools

AgentRuntime calls your server and imports the tool catalog and config schema. If discovery returns zero tools, check that the URL is correct and the MCP endpoint is running.
5

Review catalog

Review discovered tools (name, input/output shape). Use Hold to inspect the list, or wait for the countdown to continue automatically.
6

Publish and activate

The wizard publishes version 1.0.0, runs validation checks, and creates a workspace instance.
7

Configure credentials

Open Instance config (/mcp/instances/{instance_id}). On the active profile, wire a connection if tools need API keys or OAuth tokens.
8

Use in Workflow Studio

Add an mcp_call step, select your instance, and pick a tool from the discovered catalog.
On success, the wizard offers Open instance → and Open server links. Server-level health checks live at /mcp/{server_id}/validate.

​
Register via API

Requires project_contributor:
Then discover, publish a version, validate, and create an instance: See API examples — MCP for full request/response samples.

​
Auth and connections

The registration wizard defaults to auth_mode: "token". Credential delivery depends on your server:
  • Connection-backed — Store secrets in Connections, bind on the instance’s active config profile (source_spec). Preferred for API keys and OAuth refresh tokens.
  • Server-side auth — If your MCP server validates its own tokens at the HTTP layer, you may not need per-instance wiring (still validate in a test run).
Do not embed secrets in workflow graphs or Lua scripts.

​
Troubleshooting