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

TypeWho publishesHow you install
Platform catalogAgentRuntime operatorsMCP → Add connectors → Add instance on a catalog row
Custom (third-party)Your workspaceMCP → Add connectors → Add connector → register URL you operate
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: 
POST /v1/mcp/servers

{
  "name": "Internal tools MCP",
  "canonical_url": "https://tools.example.com/mcp",
  "description": "CRM and billing helpers",
  "mode": "third_party",
  "auth_mode": "token"
}
Then discover, publish a version, validate, and create an instance:
StepEndpoint
Discover toolsPOST /v1/mcp/servers/{id}/discover
Publish versionPOST /v1/mcp/servers/{id}/versions with tools, config_schema, activate: true
ValidatePOST /v1/mcp/servers/{id}/validate
Add instancePOST /v1/mcp/instances with { "server_id": "…" }
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

SymptomFix
No tools discoveredConfirm URL, TLS, and that the MCP handshake returns tools. Test with curl from your network.
Validation failedOpen /mcp/{server_id}/validate for per-check messages (reachability, schema, smoke call).
Tools missing in Workflow StudioEnsure the instance exists and the active config profile is set. Save and re-open the workflow.
401 / 403 at runtimeWire the correct connection on Instance config or fix server-side auth.