Webinar: Better Agents, Easier than Ever — Thursday, June 18th at 9am PT / 12pm ET. Register Now
Version 2.5
First-time setup
Set up MCP orchestration

Set up MCP orchestration

Beyond the vendor remote MCPs and the Sema4.ai MCP Gallery, you can connect your own custom MCP servers to the platform. Sema4.ai does not host these for you — you run them on your own infrastructure (the "orchestration"), then register each server's URL on an agent.

This page covers the requirements every host must meet and the hosting targets we recommend. Each target has its own walkthrough.

The MCP server itself is the same in every case. What differs per target is the container image's base, how ingress is configured, and how secrets are injected.

Requirements

Whatever you host on, your MCP deployment must provide:

  • Streamable-HTTP transport — Sema4.ai connects to remote MCPs over HTTP only. stdio is not supported.
  • Session affinity (sticky sessions) on the load balancer or ingress — MCP sessions are stateful per connection. Without affinity, requests get balanced across instances and sessions break.
  • Secrets wiring — inject anything your MCP reads from the environment (API keys, tokens) using the platform's native secret manager.
  • A health endpoint — if the platform expects one (all targets below do).
  • Network line of sight — the Sema4.ai platform must be able to reach the MCP's URL over the network. If you host the MCP on private ingress (internal-only Cloud Run, an internal ALB, private subnets, a VPC-attached runtime), make sure the platform's network can route to it and that any firewall, security group, or NSG rules allow the connection.

The MCP endpoint is served at the /mcp path. The URL you register on an agent always ends in /mcp — for example https://my-mcp.example.com/mcp.

Recommended hosting targets

Pick the one that matches your cloud. The MCP is identical across them.

TargetBest for
Google Cloud RunTeams already on GCP; the simplest setup.
AWS ECS FargateAWS-first stacks wanting a long-running container behind an ALB.
Azure Container AppsAzure-first stacks.
Snowflake SPCSTeams on Snowflake who want the MCP inside the account boundary.

One MCP per service, or many behind one gateway

Each subpage deploys one MCP per service, which is the simplest model and what most teams start with.

If you're hosting several custom MCPs and don't want a separate service per MCP, you can use the multi-MCP gateway pattern: a single container running an Nginx reverse proxy that routes by path prefix to several MCP processes, each in its own virtual environment on its own internal port.

 https://gateway.example.com/sharepoint/mcp  ─▶  nginx :8080 ─▶ :8001
 https://gateway.example.com/slack/mcp       ─▶              ─▶ :8002
 https://gateway.example.com/linear/mcp      ─▶              ─▶ :8003

Each MCP is still registered independently on the agent with its own URL — the gateway is a hosting convenience, not a combined interface. This is the same pattern the Sema4.ai MCP Gallery uses internally. The gateway container is just a container, so deploy it to any of the targets above.

Register an MCP with an agent

Once a server is running and reachable, an agent builder adds it to an agent by its URL (ending in /mcp). Custom MCP servers handle their own authentication — a forwarded Authorization: Bearer token or an X-Api-Key header passed through from the agent.

Set up OAuth for MCPsGoogle Cloud Run