docsconceptscapabilities

Capabilities

A Cast agent on its own can think and talk. Capabilities are how it acts in the world — reading your email, fetching a page, watching your calendar, messaging a colleague.

Cast deliberately ships with nothing built in. Every capability comes from an extension, a service you write, or an MCP server plugged in from outside.

Use an extension

An extension wraps a real-world capability — reading email, watching a calendar, fetching a page — and exposes it as tools the agent can call. An agent opts in to the extensions it needs, and the tools appear. See Extensions for what Cast ships with.

agent
Did anyone email about the launch?
✉emailsearch inbox — "launch"
Three threads this week. Sarah confirmed Tuesday, marketing wants a draft by Friday, and Alex flagged a copy issue.
📖 JARGON
Aren't these just MCP servers? Under the hood, an extension's tools reach the agent through the same MCP protocol an external MCP server would. But an extension does more — it can hold long-running state (an IMAP IDLE connection, say), push messages into a conversation, contribute to the agent's system prompt, and gate sensitive actions behind approvals. MCP is the wire; an extension is the package around it.

Add an agent service

When you need a capability no extension provides, an agent service fills the gap. It is custom, ad-hoc code that runs alongside one specific agent — a private extension authored for that agent alone. The service runs on the host, outside the sandbox, so its reach is effectively unlimited: any API your machine can talk to, any subprocess it can run, any port it can listen on.

You author a service in advanced mode — the supervised coding loop. From Claude Code, run /cast-build <folder> and describe what you want the agent to be able to do. Claude Code writes the code; you review every diff before it lands.

What a service can do:

  • Hold a long-running connection — websocket, IMAP IDLE, a polling loop — and push to the agent the moment something happens.
  • Listen for webhooks: OAuth callbacks, third-party event deliveries, anything that calls back to your machine.
  • Talk to internal or proprietary APIs with credentials the agent never sees.
  • Spawn and manage subprocesses — CLIs, Python scripts, anything the host can run — and feed the output back to the agent.
  • Maintain a queryable index that persists across conversations, exposed to the agent as a search tool.
📖 JARGON
Services run host-side, outside the agent's container. That is why the capability ceiling is the host's, not the agent's. The trade-off: a service is fully trusted code on your machine. See Writing services for the framework and IPC contract.

Plug in an MCP server

When someone has already published an MCP server for what you need, Cast can plug it in directly — no need to rewrite it as an extension or a service. The trade-off lives in the trust column.

💡 TIP
External MCP support is experimental for now. Expect rough edges and possible breaking changes as it matures.
⚠ HEADS UP
An MCP server is third-party code that can do whatever its code allows. The agent reads its tool descriptions and outputs as context, so a compromised server can manipulate the agent through either. MCP servers also lack the framework surfaces an extension provides — no lifecycle hooks, no typed config, no approval gates, no prompt contribution, no way to push into a conversation. Prefer reputable vendors and read-only tools when you do use one. For anything load-bearing, an extension or a service is the safer reach.