MCP Server

Custral runs a Model Context Protocol server, so you can add your workspace as a tool source in Claude Desktop, Cursor, or any MCP client and let the model read your data on your behalf.

Endpoint

https://api.custral.com/v1/mcp

It speaks MCP over streamable HTTP. There are two ways to authenticate, and for most people the first one means never handling a key at all.

Connect a client

Point your client at the endpoint and let it walk you through signing in. No key to create, copy, or store.

claude mcp add --transport http custral https://api.custral.com/v1/mcp

{
  "mcpServers": {
    "custral": {
      "url": "https://api.custral.com/v1/mcp"
    }
  }
}

Notice there’s no Authorization header. The first time the client calls the server it gets a 401 telling it where to authenticate, and it opens your browser:

Approve the connection

Custral shows you which application is asking, which workspace it will act on, and a plain-language list of exactly what it will be able to do. Pick the workspace and choose Authorize.

You're connected

The browser hands the client its credential and closes. Nothing is ever displayed for you to copy.

Behind the scenes this is standard OAuth 2.1 with PKCE: the client registers itself, you approve in the browser, and it exchanges the result for a scoped key. The endpoint’s 401 challenge tells the client which scopes to ask for (WWW-Authenticate: Bearer resource_metadata="…", scope="…"): every read scope, mcp:write and every write scope. Key, connector and webhook management are never requested, and you see the full list on the approval screen before you authorize. What it receives is an ordinary Custral API key, so it appears in Settings → Applications alongside any you made by hand, shows when it was last used, and is revoked the same way.

Approving grants access to one workspace. The one you pick on the approval screen. To connect a second workspace, add the server again under a different name and choose that workspace when you approve.

With an API key

Use a key when the client isn’t a browser-capable machine (CI, a server, a container) or when you want to pin an integration to an exact scope set. The custral CLI mints a scoped key and prints a ready-to-paste config for each client:

custral login   # once, if you haven't
custral mcp

For Claude Code, it prints a command you can run as-is:

claude mcp add --transport http custral https://api.custral.com/v1/mcp \
  --header "Authorization: Bearer sk_live_..."

For Claude Desktop or Cursor, it prints a JSON block to drop into your MCP config:

{
  "mcpServers": {
    "custral": {
      "url": "https://api.custral.com/v1/mcp",
      "headers": {"Authorization": "Bearer sk_live_..."}
    }
  }
}

You can also create the key yourself in Settings → Applications. Either way it needs the mcp:read scope to connect, plus the same resource scopes the REST API asks for: records:read to search and read records, objects:read for object schemas, conversations:read for conversations, and so on. Writes need mcp:write plus a write scope per write action: records:write to create and update records, conversations:write to change conversations, applications:manage to mint keys, webhooks:manage to register webhooks.

A secret key (sk_…) can read and write your workspace. Keep it out of browsers and out of version control, and revoke it in Settings → Applications if it leaks.

Use it

Talk to the agent in natural language. It picks the right tools and stays scoped to the one workspace the connection was granted for. For example:

“Summarize my open conversations and tell me which need a reply.”, reads conversations + their transcripts.
“Mark conversation conv_3Ab… as closed and set the outcome to won.”, set_conversation_status + set_conversation_disposition (needs conversations:write).
“Find the contact jane@acme.com and set their status to customer.”. Searches records, then update_record (needs records:write).
“Create a deal named Globex on the deals object.”, create_record (needs records:write).

The agent can only do what the connection’s scopes allow. mcp:read only lets a client connect: with it alone the agent can search Custral’s docs, but it cannot read your workspace until the connection also holds the read scope for each resource.

What’s exposed

Read is a read-only subset of your workspace tools. Every read tool needs mcp:read plus the scope its resource needs on the REST API, so a key cannot read more over MCP than it could over /v1:

Reads	Requires
Records, lists, record files and timelines	`records:read`
Objects, properties, record templates and forms	`objects:read`
Documents, pages, views and your knowledge base	`documents:read`
Conversations, email, voicemail, coaching, playbooks and snippets	`conversations:read`
Tasks	`tasks:read`
Auto-fills	`property_agents:read`
Usage modules and events	`usage:read`
Quotes, contracts, invoices, subscriptions and revenue	`billing:read`
Connectors	`connectors:read`
The chat widget’s settings	`widget:manage`
Calendar, scheduling, workflows, jobs, sequences, teams and other workspace setup	every `*:read` scope
A full workspace export (`export_workspace`), for a key created by a workspace admin	every `*:read` scope and `applications:manage`
Custral’s own docs	`mcp:read` only

A read tool with no scope mapping is never exposed. Write is a small, curated set of provisioning actions. Every one needs mcp:write, plus its own resource scope so keys stay least-privilege:

Tool	Requires	Does
`create_record`	`records:write`	Create a record on any object
`update_record`	`records:write`	Update a record’s fields
`enrich_record`	`records:write`	Run a record’s auto-fills
`update_document`	`documents:write`	Replace an existing document’s content
`set_conversation_status`	`conversations:write`	Set a conversation’s status (`open` / `closed` / `completed`)
`set_conversation_disposition`	`conversations:write`	Set a conversation’s outcome
`create_property_agent`	`property_agents:write`	Set up an auto-fill on a property
`update_property_agent`	`property_agents:write`	Change an auto-fill
`create_usage_module`	`usage:write`	Set up a usage module
`upsert_widget_page_prompts`	`widget:manage`	Add or change page prompts on the website chat widget
`remove_widget_page_prompt`	`widget:manage`	Remove the page prompt for one page
`set_widget_suggested_questions`	`widget:manage`	Set the widget’s suggested questions and “Talk to a person” button
`set_widget_behavior`	`widget:manage`	Set the widget’s launcher, message sounds and page-note limits
`create_application`	`applications:manage`	Create a developer application
`create_api_key`	`applications:manage`	Mint a scoped API key (returned once)
`create_webhook_endpoint`	`webhooks:manage`	Register an outbound webhook (signing secret returned once)
`create_custom_connector`	`connectors:manage`	Add a custom connector (an MCP server Stella can use)

A tool only appears when the connection holds mcp:write and its scope, so a mcp:write + webhooks:manage key can register webhooks but cannot mint keys, and vice-versa. Every other write in Stella’s toolbox stays off the MCP surface entirely. The allowlist is explicit, not “all writes.” The scopes are the authorization, however you connected: with a key you choose them when you create it, and with browser sign-in you see them listed on the approval screen before you authorize. There is no per-action prompt once a client is connected. MCP clients run headless, so the grant is made once, up front.

Preview the tools

To see exactly which tools a key exposes (the same list an MCP client receives from tools/list, without wiring up a client) call:

curl https://api.custral.com/v1/mcp/tools \
  -H "Authorization: Bearer sk_live_..."

It returns { endpoint, scopes, count, tools: [{ name, description, inputSchema }] } and requires the mcp:read scope. (This one is a plain HTTP call, so it needs a key. A browser-authorized client reads the same list through tools/list.) scopes echoes the key’s grants, and tools includes exactly the write actions those scopes unlock, so it doubles as a quick check that your key is configured the way you expect.

This is Custral acting as an MCP server (a client connects to your workspace). It is separate from connecting Stella to other people’s MCP servers, which is configured in Settings → Integrations → MCP.

Authentication: browser sign-in, creating a key by hand, and what each scope grants.
API Reference: the equivalent REST surface.

SDKs

Tools

Endpoint

Connect a client

With an API key

Use it

What’s exposed

Preview the tools

​Endpoint

​Connect a client

​Sign in through your browser (recommended)

​With an API key

​Use it

​What’s exposed

​Preview the tools

​Related

Endpoint

Connect a client

Sign in through your browser (recommended)

With an API key

Use it

What’s exposed

Preview the tools

Related