turtles connect mcp

Connect MCP (Model Context Protocol) servers to extend your Turtles with external tools.

Any MCP-compatible server can be connected — file systems, databases, APIs, developer tools, and more. OpenTurtles supports stdio, HTTP, and SSE transports.

turtles connect mcp add

Manage MCP (Model Context Protocol) servers

Usage: turtles connect mcp add [OPTIONS] <NAME>

Arguments:
  <NAME>  Server name

Options:
      --json <JSON>          Add from JSON config string
      --command <COMMAND>    Command for stdio transport
      --args <ARGS>          Args for stdio transport (space-separated)
      --url <URL>            URL for http/sse transport
      --env <KEY=VALUE>      Environment variables (repeatable)
  -h, --help                 Print help

stdio transport

Connect a locally-installed MCP server via stdin/stdout:

$ turtles connect mcp add filesystem \
    --command npx \
    --args "-y @modelcontextprotocol/server-filesystem /Users/me/Documents"

  ✓ Added MCP server 'filesystem' (stdio).

With environment variables:

$ turtles connect mcp add github \
    --command npx \
    --args "-y @modelcontextprotocol/server-github" \
    --env GITHUB_TOKEN=ghp_xxxxxxxxxxxx

  ✓ Added MCP server 'github' (stdio).

HTTP transport

Connect to a remote MCP server via Streamable HTTP:

$ turtles connect mcp add remote-tools --url https://api.example.com/mcp

  ✓ Added MCP server 'remote-tools' (http).

JSON config

Import a full config object directly:

$ turtles connect mcp add myserver --json '{
  "transport": "stdio",
  "command": "node",
  "args": ["server.js"],
  "env": { "PORT": "3001" }
}'

  ✓ Added MCP server 'myserver'.

turtles connect mcp test

Test connection and discover available tools:

$ turtles connect mcp test filesystem

  ✓ Connected! 4 tools available.

    • read_file
      Read the complete contents of a file
    • write_file
      Create or overwrite a file with content
    • list_directory
      List files and directories at the given path
    • search_files
      Search for files matching a pattern

turtles connect mcp list

$ turtles connect mcp list

  🔌 MCP Servers

  filesystem npx -y @modelcontextprotocol/server-filesystem /Users/me/Documents [stdio]
  github npx -y @modelcontextprotocol/server-github [stdio]
  remote-tools https://api.example.com/mcp [http]

Disconnect

$ turtles disconnect mcp:filesystem
  ✓ Disconnected MCP server 'filesystem'.

Configuration

MCP configs are stored at ~/.turtles/mcp/servers.json:

{
  "filesystem": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
  },
  "remote-tools": {
    "transport": "http",
    "url": "https://api.example.com/mcp"
  }
}

Once connected, MCP tools are automatically available to all Turtles. When you create or update a Turtle, the DNA compiler discovers MCP tools and uses them as needed.