@turtini/mcp — letting AI-IDE agents collaborate with your Turtini org

@turtini/mcp is a Model Context Protocol server that exposes your Turtini org as a first-class tool surface for AI-IDE agents. Once configured, an agent in Cursor, Claude Code, Windsurf, or Continue can read your CRM contacts, draft articles, list events, and more — directly from inside the IDE, while it's coding for you.

Claude Code shortcut: if you use Claude Code, install the official Turtini plugin instead of hand-editing config — it bundles the MCP server entry and ships a /turtini slash command for guided setup. See "Connecting Claude Code to your Turtini workspace" or run: claude plugin install github.com/Turtini/claude-code-plugin

Why this exists:
You're already pasting context from Turtini into your AI assistant ("here's our latest customer list", "here are the events we've shipped"). With @turtini/mcp, the agent fetches that context itself, on demand, scoped to exactly what you authorized.

What's exposed (today):
• auth_whoami — verify which org and scopes the agent is connected as
• contact_list, contact_create
• article_list, article_create (drafts only — admins still publish)
• event_list, event_create
• account_list
• opportunity_list
• org_context_query — natural-language org questions (Layer D / Wally bridge). The agent picks this up automatically when you ask things like "summarize the last week" or "what modules are active?"

The tool surface mirrors the @turtini/sdk Public API client. New endpoints added there flow into MCP automatically.

Setup:
1. Generate an API key in Turtini with the scopes you want the agent to have. Less is more — give the agent only the scopes it needs.
2. Install:
npm install -g @turtini/mcp
3. Configure your IDE.

Cursor (Settings → MCP) / Windsurf (Settings → Model Context Protocol):
{
"mcpServers": {
"turtini": {
"command": "npx",
"args": ["-y", "@turtini/mcp"],
"env": { "TURTINI_API_KEY": "turtini_<your-key>" }
}
}
}

Claude Code:
claude mcp add turtini -e TURTINI_API_KEY=turtini_<your-key> -- npx -y @turtini/mcp

Continue (.continue/config.json):
"experimental": { "modelContextProtocolServers": [
{ "transport": { "type": "stdio", "command": "npx", "args": ["-y", "@turtini/mcp"] },
"env": { "TURTINI_API_KEY": "turtini_<your-key>" } }
]}

Environment variables:
• TURTINI_API_KEY (required)
• TURTINI_BASE_URL (optional — defaults to https://api.turtini.com)
• TURTINI_TIMEOUT_MS (optional — defaults to 30000)

Scope discipline:
The agent can only do what the API key can do. To let an agent draft articles but not see contacts, generate a key with articles:write only. To give it read-only org context, *:read is fine. Never give an agent *:write unless you really want it creating data unsupervised.

Rotating: when you're done with a project, revoke the key from Settings → Developer. The agent immediately loses access — no IDE config change needed.

Errors surface as structured isError responses so the agent can read code/message/status and react (e.g. ask you to grant a missing scope) instead of crashing.

Source / issues: github.com/turtini/sdk-public/tree/main/packages/mcp.