API & MCP Documentation

Overview

Tootela exposes the full platform via a single JSON-RPC 2.0 endpoint that is fully compatible with the Model Context Protocol (MCP). One endpoint, 40+ tools, 9 modules. This means you can:

• Call any tool directly from Python, JavaScript, curl, or any HTTP client
• Connect any MCP-compatible AI agent (Claude, GPT, Gemini, and more) to your whole Tootela workspace
• Automate across CRM (contacts, deals, pipelines), Projects (tasks, sprints, epics), Helpdesk (tickets, replies), HR (employees, leave), Expenses, Onboarding, Recruitment, and Forms
• Build outreach scripts that discover leads, draft emails, and sync deals to the right pipeline

Authentication

All requests require a Bearer token. Generate one in your workspace at Settings → API Tokens.

Authorization: Bearer tla_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tokens are scoped to your organisation. Use environment variables — never hardcode them.

MCP Server

Add Tootela to any MCP-compatible AI client (Claude Desktop, Cursor, Windsurf, and more) and let it create contacts, log activities, and manage deals directly from your workflow.

MCP client config

Most MCP clients accept a config like this (example: Claude Desktop at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tootela": {
      "url": "https://api.tootela.net/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer tla_YOUR_TOKEN_HERE"
      }
    }
  }
}

Request envelope

Every call uses the same JSON-RPC 2.0 structure:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "create_company",
    "arguments": {
      "name": "Acme Corp",
      "domain": "acme.com",
      "industry": "SaaS"
    }
  }
}

CRM & Email

Manage contacts, companies, deals, pipelines, activities, and send personalised emails.

name* = required.

Custom Fields

Custom fields let you extend companies, contacts, and deals with organisation-specific attributes (e.g. Contact Page URL, Lead Source, Outreach Status).

Data model: custom field values are stored on the entity itself, inside a custom_fields JSONB column keyed by field_key. Use the set_*_custom_field tools below : they resolve the field_key from the definition and merge into the JSONB so the UI picks the value up immediately.

name* = required.

Projects

Manage projects, tasks, sprints, and epics. All operations are scoped to the token's organisation.

Helpdesk

Manage support tickets, replies, and statuses.

HR

Access employees, departments, and leave requests.

Expenses

List, approve, or reject expense reports. Approvals respect the multi-step approval chain.

Onboarding

Track new hire onboarding journeys and task completion.

Recruitment

Manage job postings and candidate pipelines.

Forms

Read published forms and their submissions.

Code Examples

Python: country-named pipeline + full outreach flow

import httpx, json, os

MCP_URL = "https://api.tootela.net/api/mcp"
TOKEN   = os.environ["TOOTELA_TOKEN"]

def call(tool, args):
    r = httpx.post(
        MCP_URL,
        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
        json={"jsonrpc": "2.0", "id": "1", "method": "tools/call",
              "params": {"name": tool, "arguments": args}},
        timeout=10,
    )
    result = r.json().get("result", {})
    content = result.get("content", [])
    return json.loads(content[0]["text"]) if content else result

# 1. Find or create a "France" pipeline
pipelines = call("list_pipelines", {})["pipelines"]
france = next((p for p in pipelines if p["name"] == "France"), None)
if not france:
    france = call("create_pipeline", {"name": "France"})["pipeline"]

# 2. Create company
company = call("create_company", {
    "name": "Acme Agency",
    "domain": "acme-agency.fr",
    "industry": "Marketing Agency",
    "city": "Bordeaux",
    "country": "France",
})["company"]

# 3. Create deal in the France pipeline
deal = call("create_deal", {
    "name": f"Outreach — {company['name']}",
    "company_id": company["id"],
    "pipeline_id": france["id"],
})["deal"]

# 4. Log the email draft as an activity
call("log_activity", {
    "type": "email",
    "title": "Cold outreach",
    "notes": "Hi team, we'd love to show you Tootela...",
    "deal_id": deal["id"],
})

curl: list pipelines

curl -X POST https://api.tootela.net/api/mcp \
  -H "Authorization: Bearer tla_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": "1",
    "method": "tools/call",
    "params": { "name": "list_pipelines", "arguments": {} }
  }'

curl: send an email

curl -X POST https://api.tootela.net/api/mcp \
  -H "Authorization: Bearer tla_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": "1",
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": "founder@startup.io",
        "to_name": "Alex",
        "subject": "Quick question about your stack",
        "body": "Hi Alex,\n\nI noticed you...",
        "reply_to": "eliot@tootela.net"
      }
    }
  }'

Error Handling

Tool errors return HTTP 200 with a JSON-RPC error object. Auth failures return HTTP 401.

// Auth failure — HTTP 401
{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Unauthorized: invalid or missing Bearer token"}}

// Tool error — HTTP 200
{"jsonrpc":"2.0","id":"1","error":{"code":-32603,"message":"duplicate key value violates unique constraint"}}

// Unknown method — HTTP 200
{"jsonrpc":"2.0","id":"1","error":{"code":-32601,"message":"Method not found: tools/unknown"}}