Surfaces: MCP

MCP (Model Context Protocol) is mashin’s implicit surface. Every machine you write is automatically available as an MCP tool with no additional configuration. MCP is how AI assistants like Claude, Cursor, ChatGPT, and VS Code discover and call your machines.

Zero configuration

Write a machine:

machine classify_email

  accepts
    subject as text, is required
    body as text, is required

  responds with
    category as text
    priority as text

  implements
    ask classify, using: "anthropic:claude-sonnet-4-6"
      with task "Classify this email by category and priority"
      returns
        category as text
        priority as text
      assuming
        category: "general"
        priority: "normal"

Start the MCP server:

mashin mcp

That is it. The machine classify_email is now available as an MCP tool. Any MCP client that connects sees it, with its input schema derived from accepts and its description derived from the machine name and structure.

How it works

The mashin MCP server implements the Model Context Protocol over stdio (JSON-RPC 2.0):

1. tools/list returns all machines in the current cell as tools, with input schemas derived from accepts
2. tools/call executes a machine with the provided inputs, runs it through governance, and returns the result
3. resources/list exposes syntax reference and documentation as MCP resources
4. resources/read returns resource contents

Every tools/call invocation:

• Checks governance permissions (the machine’s ensures section)
• Records a SurfaceAccess event with :mcp surface in the behavioral ledger
• Enforces budget limits
• Returns structured output matching responds with

Connecting MCP clients

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mashin": {
      "command": "mashin",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop. Your machines appear as tools in the tool list.

Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "mashin": {
      "command": "mashin",
      "args": ["mcp"]
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings or MCP configuration:

{
  "mcpServers": {
    "mashin": {
      "command": "mashin",
      "args": ["mcp"]
    }
  }
}

Any MCP client

The mashin MCP server speaks standard JSON-RPC 2.0 over stdio. Any client that implements the MCP protocol can connect by spawning mashin mcp as a subprocess.

Tool naming

MCP tools are named after the machine. For machines with multiple chains, each chain becomes a separate tool:

Machine	MCP tool name
classify_email	classify_email
data_pipeline (single chain)	data_pipeline
multi_tool with chains search and count	multi_tool/search, multi_tool/count

Input schema generation

The accepts section maps directly to the MCP tool’s input schema:

accepts
  query as text, is required
  max_results as number
  include_archived as boolean

Becomes:

{
  "type": "object",
  "properties": {
    "query": {"type": "string"},
    "max_results": {"type": "number"},
    "include_archived": {"type": "boolean"}
  },
  "required": ["query"]
}

MCP resources

The MCP server also exposes documentation as resources. Clients that support resources/list and resources/read can access:

• mashinTalk syntax reference
• Step type documentation
• Expression language reference

This lets AI assistants that connect via MCP understand the mashin language and help you write machines.

Trust levels

MCP connections have three trust levels:

Level	Access	When
System	All tools including dev tools	Local stdio from Koda desktop
Authenticated	Standard tools, scoped to caller’s org	Valid API key or bearer token
Untrusted	Public tools only (health, docs)	No authentication

Local connections from mashin mcp run at system trust. Remote MCP endpoints (if exposed) require authentication.

Rate limiting

MCP tool calls are rate-limited per organization, per minute. System-trust calls (local stdio) are exempt. Rate limits are configured at the cell level and enforced by the MCP server.

Example: using a machine from Claude

After connecting the MCP server, you can use machines conversationally:

“Classify this email: Subject is ‘Q3 Board Meeting’, body is ‘Please review the attached deck before Friday.’”

Claude calls the classify_email tool, which runs through mashin’s governance, and returns:

Category: meetings, Priority: high

The behavioral ledger records the invocation, the governance check, and the result.

Next steps

• REST API surface - Expose machines as HTTP endpoints
• Surfaces overview - All surface types
• CLI Reference - mashin mcp command details