Tools with MCP

Agents take action through tools, and tools are provided over MCP (Model Context Protocol). Attaching an MCP server to an agent gives it that server's tools — reading email, querying a CRM, searching the web, calling your own systems.

Where tools come from

There are three sources (an admin sets these up; see MCP servers):

• Vendor remote MCPs — third-party, vendor-hosted servers (Linear, GitHub, Notion, Stripe, and more), preconfigured and available out of the box.
• The Sema4.ai MCP Gallery — Sema4.ai-provided servers for Google Workspace, Microsoft 365, web search, and more.
• Custom MCPs — your own servers, hosted on your infrastructure and connected to the platform.

Adding tools to an agent

In the agent editor, attach the MCP servers the agent needs; its tools then become available to the runbook. Reference a tool from the runbook by describing when to use it.

• Pick a subset of tools. You don't have to expose a whole server — in the edit view you can select just the specific tools the agent should have. Fewer, relevant tools keep the agent focused and reliable.
• Only connected servers can be attached. A server has to be authenticated/connected before it can be added to an agent — see Tools that need authentication.
• Worker agents support only non-user-authenticated servers. A Worker agent processes shared Work Items that aren't scoped to an individual user, so it can't use tools that act on behalf of a specific signed-in person. Give Workers workspace-level (non-user-auth) servers; user-authenticated servers are for Conversational agents, where a real user is present to authorize them.

Developing custom MCPs

When you build your own MCP server, the tools you write shape how well agents can use them. A few recommendations from experience:

• Design tools for the model, not for your API. Tool names and descriptions are what the agent reasons over — use clear, verb-based names (create_invoice, not endpoint2) and describe when to use the tool, not just what it does. One tool per intent beats one generic tool with a mode parameter.
• Return concise, structured results. The agent reads the whole result; a compact JSON answer beats a dump of everything your backend knows. When something fails, return an error message the agent can act on ("customer 4711 not found — check the ID") rather than a stack trace.
• Use the platform context your server receives. On every call, Sema4.ai passes invocation context to your MCP server — the thread ID, the calling user, and API access to the conversation — so tools can work with the thread's files and data frames instead of asking the user to re-supply them. The agent-server example (opens in a new tab) is a working server showing how to share thread ID, files, data frames, user identity, and more between the agent and your tools.
• Keep every tool call well under five minutes. The platform waits at most 300 seconds for a single tool call to return. If a call runs longer, the agent's request times out and the run fails — and because no cancellation is sent to your server, the work keeps running there with nobody waiting for the result.

Long-running work: submit and poll

For anything that can exceed the window — report generation, batch processing, external pipelines — don't hold the tool call open. Split the operation into asynchronous halves:

1. A start tool that kicks off the job and returns immediately with a job ID: start_report(params) → { "job_id": "abc-123", "status": "running" }
2. A status tool that is always fast: get_report_status(job_id) → { "status": "running" | "done" | "failed", "result": … }

Then tell the agent how to use the pair in the runbook, for example:

Start the report with start_report, then check get_report_status periodically until it is done, and present the result. If it is still running after several checks, tell the user it's in progress and how to follow up.

This keeps every individual tool call fast, survives restarts on either side, and gives the user visible progress instead of a five-minute silence followed by a timeout.