DOCSEARCHbyAlgolia
Submit Docs

Twenty Documentation

website·Indexed 35 days ago

https://twenty.com/user-guide

Developer and user guides for Twenty, featuring documentation on APIs, schema-per-tenant APIs, and MCP Server capabilities including authentication methods.

Tokens
1.9K
Snippets
7
Records
20
Agent score
73%

What's inside Twenty

  2. Integrate with Twenty APIs

    Twenty provides multiple integration methods for developers, including REST and GraphQL APIs, webhooks, and OAuth for authentication and authorization.

  3. Connect an AI assistant to Twenty via MCP

    Twenty provides an MCP (Model Context Protocol) server that allows AI assistants like Claude Desktop, Claude Code, Cursor, and ChatGPT to read and write CRM data using natural language. The MCP endpoint is located at https://{your-workspace-url}/mcp for both Cloud and Self-Hosted environments.

  4. Understand Twenty's schema-per-tenant API generation

    Twenty does not have a static API reference because APIs are dynamically generated from each workspace's unique schema. When custom objects (e.g., Invoice) are added, REST and GraphQL endpoints are automatically created using the object and field names. Workspace-specific interactive documentation and a playground are available in Settings → API & Webhooks after an API key is created.

  7. Authenticate Twenty CRM MCP Server requests

    Authentication for the Twenty CRM MCP server is handled via the Authorization header. There are two supported methods:

    1. Static API Key: Provide a Bearer <api-key> token in the Authorization header.
    2. OAuth 2.1: Omit the Authorization header to use OAuth 2.1, which is automatically discovered via the workspace host's /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server endpoints.

  8. Use Twenty MCP tools for CRM operations

    The MCP server exposes tools that mirror the Twenty API. AI assistants typically use the following workflow:

    1. learn_tools: Used to get the input schema for specific tools.
    2. execute_tool: Used to run the tool.

    Operation names follow a predictable grammar (e.g., find_many_companies, find_one_person, update_one_opportunity). For a full list of tools, get_tool_catalog can be used, though it is recommended as a fallback due to the high volume of operations.

  9. Locate MCP configuration files for common AI clients

    Depending on the AI assistant you are using, the MCP configuration JSON should be placed in the following locations:
    ClientConfig file location
    Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
    Claude Code~/.claude.json (user) or .mcp.json (project)
    Cursor.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
    ChatGPTEnable Developer Mode in Settings → Apps & Connectors → Advanced settings, then use Create in Settings → Apps & Connectors

  10. Configure Twenty CRM Model Context Protocol (MCP) Server

    The Twenty CRM MCP server allows AI assistants to read and write CRM data, including companies, people, opportunities, tasks, notes, and custom objects. Tools are discovered at runtime and scoped to the authenticated workspace. The server uses a streamable-http remote connection.
    {
  "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
  "name": "com.twenty/twenty",
  "version": "0.2.1",
  "title": "Twenty CRM",
  "description": "Read and write your Twenty CRM data - companies, people, opportunities, tasks, notes and any custom objects - from AI assistants.",
  "websiteUrl": "https://twenty.com",
  "repository": {
    "url": "https://github.com/twentyhq/twenty",
    "source": "github"
  },
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp",
      "supportedProtocolVersions": [
        "2025-06-18"
      ],
      "headers": [
        {
          "name": "Authorization",
          "description": "Optional. Bearer <api-key> for static API-key auth. Omit to use OAuth 2.1.",
          "isRequired": false,
          "isSecret": true
        }
      ]
    }
  ]
}

  11. Distinguish between Core and Metadata APIs

    Twenty provides two distinct API sets, both available via REST and GraphQL:

    1. Core API (/rest/ and /graphql/): Used for CRUD operations on records such as People, Companies, Opportunities, and custom objects. Supports querying, filtering, and traversing relations.
    2. Metadata API (/rest/metadata/ and /metadata/): Used for programmatic schema management, including creating, modifying, or deleting objects, fields, and relations.

  12. Configure Twenty MCP server using an API Key

    Use an API key if your MCP client does not support OAuth or if you prefer static credentials. The API key must be passed in the Authorization header. You can create an API key in Twenty by navigating to Settings → MCP & APIs → API → + Create key.
    {
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}