@turtini/mcp

Turtini MCP server — exposes the Turtini Public API as Model Context Protocol tools, so AI agents in your IDE (Cursor, Claude Code, Windsurf, Continue, …) can read and write your org's data while they code.

// What your IDE's AI agent can now do, on its own:

await turtini.contact_create({
  firstName: 'Ada',
  lastName:  'Lovelace',
  email:     '[email protected]',
})

const articles = await turtini.article_list({ limit: 5 })

That's nine tools out of the box: auth_whoami, contact_list, contact_create, article_list, article_create, event_list, event_create, account_list, opportunity_list. The agent picks them up automatically as soon as the server is wired into your IDE.

Setup

1. Mint a Turtini API key

Go to Settings → Partner Dev → API Keys in the Turtini app. Create a key with the scopes the agent should be able to use — e.g. contacts:read, contacts:write, articles:read, articles:write, events:read, events:write. The plaintext key is shown once — copy it.

2. Add the MCP server to your IDE

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in a project for per-project config):

{
  "mcpServers": {
    "turtini": {
      "command": "npx",
      "args":    ["-y", "@turtini/mcp"],
      "env":     { "TURTINI_API_KEY": "turtini_..." }
    }
  }
}

Claude Code

claude mcp add turtini -- npx -y @turtini/mcp

…then set the env var:

claude mcp env turtini TURTINI_API_KEY turtini_...

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "turtini": {
      "command": "npx",
      "args":    ["-y", "@turtini/mcp"],
      "env":     { "TURTINI_API_KEY": "turtini_..." }
    }
  }
}

Continue (VS Code / JetBrains)

.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [{
      "transport": {
        "type":    "stdio",
        "command": "npx",
        "args":    ["-y", "@turtini/mcp"],
        "env":     { "TURTINI_API_KEY": "turtini_..." }
      }
    }]
  }
}

3. Verify

Restart your IDE, open a chat, and ask:

"Use the turtini tools to whoami and tell me which org I'm connected to."

The agent should call auth_whoami and report back your org name.

Tools

| Tool | What it does | Required scope | |------|--------------|----------------| | auth_whoami | Confirm which org the API key grants access to. | any | | contact_list | List CRM contacts (paginated, newest-first). | contacts:read | | contact_create | Create a new contact. | contacts:write | | article_list | List articles authored by the org. | articles:read | | article_create | Create a new article (always saved as draft). | articles:write | | event_list | List events on the org calendar. | events:read | | event_create | Create a new event. | events:write | | account_list | List accounts in the CRM. | accounts:read | | opportunity_list | List opportunities in the sales pipeline. | opportunities:read |

The wildcard scope *:read covers every read tool, *:write covers every write tool. They don't imply each other — combine both for full access.

Articles created via this server are always status: 'draft' — publish through the in-app review workflow, not via the API. AI-generated drafts shouldn't bypass your editorial checks.

Configuration

| Env var | Default | Purpose | |---------|---------|---------| | TURTINI_API_KEY | required | Org-scoped API key (turtini_…). | | TURTINI_BASE_URL | https://api.turtini.com | Override for self-hosted / staging environments. | | TURTINI_TIMEOUT_MS | 30000 | Per-request timeout. |

How this fits

@turtini/mcp wraps the @turtini/sdk Public API client in MCP protocol. If you want to call the Turtini API directly from application code (server functions, CLI tools, exported static sites), use @turtini/sdk instead — same surface, no MCP wrapper.

This is Layer B of Turtini's developer-platform roadmap. Layer A is the SDK itself; Layers C and D add live dev-environment proxying and AI-shared org context.

License

MIT.