FAQ

What is Routecraft?

Routecraft is the open source AI automation platform your teams build on together. You build a capability once, as a typed TypeScript route, and every agent, editor and schedule in the organisation can call it, on service credentials the platform holds. What is Routecraft covers the model.

What is the difference between a capability and a context?

A capability is one thing your harness can do: a typed route that says how a call reaches it, what every call is checked against, and the steps that do the work. A context is the runtime that loads the capabilities and plugins, runs their lifecycle, and provides shared services such as logging and the store; craft start builds one for you. Capabilities takes a capability apart.

What is the difference between the local harness and the team harness?

They are the same project in two places. The local harness runs on your laptop on your own credentials, and nobody else can reach it; the team harness is that project deployed, always on, with the organisation's service credentials and its doors behind authentication. Local harness, team harness covers how a capability moves from one to the other.

Should I serve MCP over stdio or HTTP?

Stdio for one person: the MCP client starts the project itself as a subprocess, with no port and no credential, and a new project is already set up for it. HTTP for a team: the tools run always on, at /mcp on the instance's server, behind authentication. Expose to an agent shows both.

Where do secrets live?

In the environment of the harness that runs the capability, read by the adapter that needs them. On your laptop that is your own .env; on the team harness it is the organisation's service credentials, which no person or agent holds. An agent calls the capability, never the system behind it, so the key never leaves the harness. Credentials and identity explains the model.

Can capabilities call each other?

Yes. One capability calls another with direct("<id>") and imports only the types the callee exports from its route.ts. Composing capabilities covers chains, fan-out and routing chosen at runtime.

How do I handle errors?

A failed exchange never stops the capability or the others beside it. With no .error() handler, the runtime logs it, emits route:error, context:error and route:exchange:failed, and processes the next exchange. Add .error() to a capability to recover with your own handler, in which case route:error:caught fires instead of the failure events; declare .input() so invalid input is refused before any step runs, and alarm on context:error as described in Monitoring. Error handling covers .error() in full.

What adapters are available?

Routecraft ships adapters for files (CSV, JSON, HTML, XML), HTTP, mail, contacts, schedules, MCP, LLMs and agents, and more. The Adapters reference lists every one with its options.

How do I create a custom adapter?

Implement the interface for the role it plays (Source, Destination, Enricher or Processor) in a class, and export a factory function that returns it. Creating adapters walks through each role, the option conventions, and how to make the adapter mockable in tests.

How do I expose a capability as an MCP tool?

Add mcp() from @routecraft/ai as a source beside direct(), give the capability a .description() and an .input() schema, and keep the mcp: {} key a new project already has in craft.config.ts. Over stdio the MCP client starts the server itself, for example claude mcp add my-tools -- bunx craft start --log-file craft.log, with the log in a file because standard output is the protocol. Expose to an agent has the steps for each client.

---

Related