Model Context Protocol (MCP)

​

What is MCP?

​

Rollout’s MCP server

• Server URL: https://mcp.rollout.com/mcp
• Transport: Streamable HTTP
• Authentication: OAuth 2.1, which any MCP client that supports remote servers can complete on its own, or a Rollout auth token sent as a Bearer token

​

Tools

​

Use it from an MCP client

​

Build with Rollout’s MCP server

​

Call it from your backend with an auth token

Authorization: Bearer <your auth token>

​

Example with Claude

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const response = await anthropic.beta.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 16000,
  betas: ["mcp-client-2025-11-20"],
  mcp_servers: [
    {
      type: "url",
      url: "https://mcp.rollout.com/mcp",
      name: "rollout",
      // The auth token you minted for this user
      authorization_token: rolloutAuthToken,
    },
  ],
  tools: [{ type: "mcp_toolset", mcp_server_name: "rollout" }],
  messages: [
    {
      role: "user",
      content: "Which of my leads haven't heard from me in two weeks?",
    },
  ],
});

for (const block of response.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}

​

Example with the MCP SDK

import {
  Client,
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/client";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.rollout.com/mcp"),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${rolloutAuthToken}` },
    },
  },
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// Give these to your model as its tools
const { tools } = await client.listTools();

// Call a tool on the model's behalf
const result = await client.callTool({
  name: "searchPeople",
  arguments: { notContactedSince: "-14d", limit: 10 },
});

​

Users without a connected account

​

Let users authorize your agent with OAuth

curl -X PUT https://mcp.rollout.com/oauth/client \
  -u "$ROLLOUT_CLIENT_ID:$ROLLOUT_CLIENT_SECRET" \
  --data-urlencode "redirect_uris=https://agent.example.com/oauth/callback" \
  --data-urlencode "redirect_uris=http://localhost:8787/oauth/callback"

https://mcp.rollout.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://agent.example.com/oauth/callback
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE
  &consumer_token=CONSUMER_TOKEN

curl -X POST https://mcp.rollout.com/oauth/token \
  -u "$ROLLOUT_CLIENT_ID:$ROLLOUT_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d redirect_uri=https://agent.example.com/oauth/callback \
  -d code_verifier=CODE_VERIFIER

{
  "access_token": "rmcp_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rmcp_rt_..."
}

​

Tool reference

• Accounts. Every tool takes an optional credentialId, one of the IDs getContext lists. Read tools cover every connected account when it is left out. Write tools need it when the user has more than one, and the error lists them.
• Names or IDs. stage, source, assignedUser and user take an ID or a name, and for users also an email, matched exactly ignoring case. When none or several match, the error lists the candidates.
• Times. An ISO 8601 date or date-time, read in UTC unless it has an offset or ends in a time zone, such as 2026-10-15[America/New_York], or a time relative to now, such as -30m, -24h, -7d, +2w, -3mo or -1y.
• Pages. Searches and the timeline return nextCursor. Pass it back as cursor for the next page. Searches also return total on the first page, exact up to 10,000, and limit: 0 returns the total alone.
• Results. Every tool returns text for the model. getContext, the searches, getTimeline and createPerson also return structuredContent for code that reads the result.
• Sync. Reads cover only the entities an account syncs. getContext shows which, and its lastInboundSyncCompletedAt is null until the first sync finishes.
• Errors. A tool that can’t do what was asked answers with an error the model can act on: an account that can’t create notes, a stage that doesn’t exist, a field the CRM requires.

​

createNote

​

createPerson

• stage and assignedUser take an ID or a name (a user also an email), matched exactly ignoring case. When none or several match, the error lists the candidates.
• Some CRMs need more than a name, such as an email or a stage from a fixed list, and some refuse a field this tool takes: getContext shows each account’s requirements.people.create, whose unsupported lists the fields the account refuses. A create that sends one gets an error.
• note is added to the person once it exists, also when the CRM returns one it already had.

​

createTask

​

getContext

• lastInboundSyncCompletedAt is null until the first sync finishes; reads find little before then.
• entitiesToSync.<entity>.enabled: reads cover only the entities that sync.
• permissions.<entity>: whether the account can list, create, update and delete that entity (people also addTag and deleteTag).
• requirements.<entity>.create: what a create needs beyond the tool’s own schema: every required field, at least one field of each anyOf group, a field in values only from its list, and no field in unsupported. requirements.<entity>.update holds an update’s.
• users: the account’s CRM users, for the tools that take one. usersListed is all up to 50 users; past that it is owners, only those who own the account’s people, out of userCount. A tool takes any user by ID, full name or email, listed or not.
• stages: the stages the account’s people are in, up to 100, in the CRM’s order where it has one, for searchPeople’s stage. Tags aren’t listed, as an account can have thousands; a tag no one has gets an error listing the closest ones.
• sources: the sources the account’s people came from, such as lead portals and ad campaigns, up to 100 by name, for searchPeople’s source.
• transactionStages and transactionSources: the same for the account’s transactions, for searchTransactions. Empty when the account can’t read transactions.
• you: when a person is signed in, the account’s users with their email, listed or not, usually one: the user “me”, “my” and “I” mean. Empty when no user has it: ask the person which user they are.

​

getTimeline

• Pass personId (from searchPeople), user, or both. Each takes one, or a list of up to 25 whose items are read together: one call instead of one per person. Without personId or from, only the last 30 days up to now are read, except open or overdue tasks, which are read whenever they are due.
• Each item has its time (occurredAt), the person and the user it belongs to, a title, a plain-text body cut to 1,000 characters, and type-specific details. A done task is placed when it was done, an open one when it is due.
• Use order: asc with from set to now for what is coming up, such as tasks due and appointments.
• When hasMore is true, pass nextCursor as cursor for the next page.
• Types an account doesn’t sync can’t be read; the answer names them.

​

logActivity

​

searchPeople

• With name, email or phone: the best matches first, each with a relevance score from 0 to 1.
• Without them: the matching people newest first, then those the CRM gives no creation time. With no filter at all, everyone.
• The first page also has total: how many people match, exact up to 10,000. limit: 0 returns the total alone; to count people by stage, call once per stage, taking the stages from getContext.
• Each person comes with the credentialId it was found in. Pass its ID and credential ID to other tools, such as createNote and createTask.
• Each comes with its assignedUser and its source, where it came from.
• Each comes with its pond, if it waits in one. unassigned: true keeps the people assigned to no user; the pond then tells a lead nobody holds from one waiting in a pond.
• Each also comes with lastHeardFrom and lastContacted, which notContactedSince and awaitingReplySince filter by, and firstContacted, whose time after the person was added is their speedToLeadSeconds. Only the calls, texts and emails an account syncs count.
• Each also comes with overdueTasks: how many of its tasks aren’t done and are past due, when the oldest was due and the users they are assigned to. hasOverdueTasks: true keeps the people with any.

​

searchTransactions

• The first page also has total: how many transactions match, exact up to 10,000. limit: 0 returns the total alone; to count transactions by stage, call once per stage.
• Each transaction comes with the credentialId it was found in, its users (the CRM users on it, such as its agents) and its people (the contacts on it, such as the buyer or seller), each with their roles where the app names them.
• stage and source are the transaction’s own, which getContext lists as transactionStages and transactionSources: not the stages people are in.
• Accounts that don’t read transactions aren’t searched, and the answer names them.