snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/user-guide/ai/capabilities/ai-agents.mdx

@@ -0,0 +1,31 @@
+---
+title: AI Agents
+description: Integrate AI capabilities directly into your automation workflows.
+---
+
+## Overview
+
+Integrate AI capabilities directly into your automation workflows for intelligent data processing and decision-making.
+
+## Capabilities
+
+| Feature | Description |
+|---------|-------------|
+| **AI actions** | Add AI-powered steps to any workflow |
+| **Data enrichment** | Automatically enhance records with external data |
+| **Classification** | Categorize records based on content analysis |
+| **Summarization** | Generate summaries from text fields |
+| **Custom prompts** | Define exactly how AI processes your data |
+
+## Use Cases
+
+- **Lead scoring**: Automatically score and prioritize inbound leads
+- **Data cleanup**: Standardize company names and contact information
+- **Email drafts**: Generate follow-up emails based on meeting notes
+- **Record routing**: Assign records to the right team member based on content
+
+## Related
+
+- [Workflows Overview](/user-guide/workflows/overview) — automation basics
+- [AI Permissions](/user-guide/ai/capabilities/permissions-access-control) — access control for AI agents
+

packages/twenty-docs/user-guide/ai/capabilities/ai-chatbot.mdx

@@ -0,0 +1,35 @@
+---
+title: AI Chatbot
+description: An intelligent assistant that helps you interact with your CRM data using natural language.
+---
+
+## Overview
+
+Ask questions in natural language and the assistant retrieves and explains your CRM data for you.
+
+## Capabilities
+
+| Feature | Description |
+|---------|-------------|
+| **Natural language queries** | Ask questions in plain English instead of building filters |
+| **Full data access** | Query records, relationships, and metrics across your workspace |
+| **Page context** | Reference "this company" or "this opportunity" based on your current view |
+| **Conversational** | Follow-up questions maintain context from previous queries |
+
+## Example Interactions
+
+### Finding Records
+- "Show me all opportunities over $50,000"
+- "Find contacts I haven't emailed in 2 weeks"
+- "List companies in the healthcare industry"
+
+### Getting Insights
+- "What's my total pipeline value?"
+- "How many deals closed last month?"
+- "Which stage has the most stuck opportunities?"
+
+### Using Page Context
+- "Summarize my interactions with this person" (on a contact page)
+- "What opportunities are linked to this company?" (on a company page)
+- "When was this deal last updated?" (on an opportunity page)
+

packages/twenty-docs/user-guide/ai/capabilities/mcp.mdx

@@ -0,0 +1,134 @@
+---
+title: MCP Server
+description: Connect AI assistants to your Twenty workspace using the Model Context Protocol.
+---
+
+Twenty exposes an [MCP](https://modelcontextprotocol.io/) server so that AI assistants — Claude Desktop, Claude Code, Cursor, ChatGPT, and others — can read and write your CRM data through natural language.
+
+Use your **workspace URL** (the URL you use to access Twenty) as the MCP endpoint. On Twenty Cloud, your workspace URL might be `https://{mycompany}.twenty.com` or a custom domain. The server is available at:
+
+| Environment | MCP Endpoint |
+|-------------|-------------|
+| **Cloud** | `https://{your-workspace-url}/mcp` (e.g. `https://mycompany.twenty.com/mcp`) |
+| **Self-Hosted** | `https://{your-domain}/mcp` |
+
+## Authentication Methods
+
+You have two ways to authenticate your MCP client: **OAuth** (recommended) or **API Key**.
+
+### Option A — OAuth (Recommended)
+
+With OAuth, your MCP client opens a browser window for you to log in. No secrets are stored in config files, and tokens refresh automatically.
+
+<Note>
+OAuth requires an MCP client that supports the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor, and ChatGPT support it.
+</Note>
+
+Add this to your MCP client configuration, replacing `{your-workspace-url}` with your workspace host (e.g. `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+That's it — no API key needed. When the client connects for the first time it will:
+
+1. Discover Twenty's OAuth metadata via `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`
+2. Register itself as an OAuth client via dynamic client registration (RFC 7591)
+3. Open your browser to authorize access
+4. Receive tokens and connect to the MCP server
+
+Subsequent connections reuse the stored tokens and refresh them automatically.
+
+### Option B — API Key
+
+If your MCP client does not support OAuth, or you prefer static credentials, pass an API key in the `Authorization` header:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+Your API key grants access to workspace data. Keep it out of version control and shared dotfiles.
+</Warning>
+
+To create an API key, go to **Settings → MCP & APIs → API → + Create key**. See [APIs](/developers/extend/api#create-an-api-key) for details.
+
+## Quick Start
+
+### 1. Copy the config
+
+Go to **Settings → MCP & APIs → MCP** in Twenty. Choose your authentication method (OAuth or API Key), copy the JSON snippet (it will already use your workspace URL), and paste it into your MCP client's config file.
+
+| Client | Config 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` in your project, or `~/.cursor/mcp.json` globally |
+| **ChatGPT** | Turn on Developer Mode in **Settings → Apps & Connectors → Advanced settings**, then use **Create** in **Settings → Apps & Connectors** to add the MCP server |
+
+### 2. Connect
+
+Restart your MCP client (or reload the config). If using OAuth you will be redirected to Twenty to authorize access. If using an API key the connection is immediate.
+
+### 3. Start using it
+
+Ask your AI assistant to interact with your CRM:
+
+- *"Show me the 5 most recently created companies"*
+- *"Create a new person named Jane Doe at Acme Corp"*
+- *"Find all open opportunities worth more than $10k"*
+
+## Available Tools
+
+Once connected, the MCP server exposes tools that mirror the Twenty API. The recommended workflow is:
+
+1. **`learn_tools`** — get the input schema for specific tools
+2. **`execute_tool`** — run a tool
+
+You don't need to remember tool names. Ask your AI assistant what it can do and it will call `learn_tools` automatically.
+
+## Permissions
+
+MCP connections inherit the permissions of the authenticated user (OAuth) or the role assigned to the API key. To restrict what the MCP server can do:
+
+- **OAuth**: The user's workspace role applies.
+- **API Key**: Assign a role to the API key under **Settings → Members → Roles**. See [Permissions](/user-guide/permissions-access/capabilities/permissions).
+
+## Self-Hosted Configuration
+
+For self-hosted instances, replace `{your-workspace-url}` with your server URL. Make sure `SERVER_URL` in your environment matches the public URL of your Twenty instance — this is used to generate the OAuth discovery metadata.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+The MCP endpoint, OAuth endpoints, and discovery metadata all derive from this value.
+
+## Troubleshooting
+
+**"Unauthorized" or 401 errors**
+- OAuth: re-authorize by clearing the stored tokens in your MCP client and reconnecting.
+- API Key: verify the key is valid and hasn't expired. Regenerate it if needed.
+
+**OAuth flow doesn't open a browser**
+- Ensure your MCP client supports MCP Authorization. Fall back to the API Key method if it doesn't.
+
+**Connection timeout**
+- Confirm the MCP endpoint URL is reachable from your machine. For self-hosted instances, check that the server is running and `SERVER_URL` is set correctly.

packages/twenty-docs/user-guide/ai/capabilities/permissions-access-control.mdx

@@ -0,0 +1,36 @@
+---
+title: Permissions & Access Control
+description: Control what AI agents can access and modify in your workspace.
+---
+
+## Overview
+
+AI agents respect your existing permission structure. This is particularly important for teams who want to control exactly what automated AI processes can access or modify in their workspace.
+
+## Assign a Role to an AI Agent
+
+1. Go to **Settings → Members → Roles**
+2. Click on the role you want to assign
+3. Open the **Assignment** tab
+4. Under **AI Agents**, click **+ Assign to AI agent**
+5. Select the AI agent from the list
+6. Confirm the assignment
+
+## Why Assign Roles to AI Agents?
+
+| Benefit | Description |
+|---------|-------------|
+| **Security** | Limit what data AI agents can access or modify |
+| **Compliance** | Ensure AI only processes the data it needs |
+| **Control** | Prevent unintended actions from AI automations |
+| **Auditability** | Track which actions were performed by which agent |
+
+<Note>
+For AI agents running within workflows, role assignment ensures the agent cannot access or modify data outside its intended scope—even if the workflow has broader permissions.
+</Note>
+
+## Related
+
+- [Permissions](/user-guide/permissions-access/capabilities/permissions) — detailed information on creating and managing roles
+- [AI Agents](/user-guide/ai/capabilities/ai-agents) — AI capabilities in workflows
+

packages/twenty-docs/user-guide/ai/how-tos/ai-faq.mdx

@@ -0,0 +1,32 @@
+---
+title: AI FAQ
+description: Frequently asked questions about AI features in Twenty.
+---
+
+<AccordionGroup>
+
+  <Accordion title="What AI capabilities are available?">
+    Two main capabilities of AI are:
+
+    1. **AI Chatbot**: A context-aware assistant that can access your Twenty data and help you with queries
+    2. **AI Agents in Workflows**: Intelligent automation that can process data, make decisions, and execute tasks within your workflows
+  </Accordion>
+
+  <Accordion title="Do AI agents have access to all my data?">
+    AI agents operate under the permission system. You can assign specific roles to AI agents under **Settings → Members → Roles**, giving you full control over what data they can access and what actions they can perform.
+  </Accordion>
+
+  <Accordion title="How do AI credits work?">
+    AI actions consume workflow credits based on the complexity of the task and the AI model used.
+  </Accordion>
+
+  <Accordion title="Can I use my own AI models?">
+    On cloud, you can use only AI models provided by Twenty. On your self-hosted instance, you can use your own AI models after obtaining an Organization license.
+  </Accordion>
+
+  <Accordion title="I don't see a role I assigned to an AI agent, where is it?">
+    By default, the Roles list is filtered to roles assignable to workspace members. If a role is assignable only to AI agents, you need to change the filter to include AI-agent roles.
+  </Accordion>
+
+</AccordionGroup>
+

packages/twenty-docs/user-guide/ai/overview.mdx

@@ -0,0 +1,54 @@
+---
+title: AI
+description: AI-powered features in Twenty.
+---
+
+<Frame>
+  <img src="/images/user-guide/workflows/robot.png" alt="AI" />
+</Frame>
+
+## Features
+
+Currently, Twenty offers:
+
+### 1. AI Chatbot
+
+A conversational assistant that understands your context and has access to all your Twenty data.
+
+**Key capabilities:**
+- **Full data access**: Query any record, relationship, or metric in your workspace
+- **Page context awareness**: Reference "this company" or "this opportunity" based on where you are in Twenty
+- **Natural language**: Ask questions and get answers without navigating menus
+
+**Example prompts:**
+- "What opportunities are closing this month?"
+- "Which deals have been in Negotiation for more than 30 days?"
+- "Summarize my interactions with this person"
+
+### 2. AI Agents in Workflows
+
+Extend your workflows with AI-powered actions and autonomous agents.
+
+**Key capabilities:**
+- **AI actions**: Use AI to enrich data, classify records, generate summaries, and more
+- **Autonomous agents**: Let agents execute multi-step tasks within a workflow
+- **Custom prompts**: Define exactly how AI should process your data
+
+**Use cases:**
+- Automatically categorize inbound leads
+- Enrich company data from public sources
+- Generate follow-up email drafts based on meeting notes
+- Score opportunities based on engagement patterns
+
+## Permissions and Access Control
+
+AI agents are managed through the existing permissions system:
+
+1. Go to **Settings → Members → Roles**
+2. Configure which data each AI agent can access
+3. Set read/write permissions per object
+
+This ensures AI agents respect your data governance policies and only access what they need.
+
+- Follow our [GitHub](https://github.com/twentyhq/twenty) for development updates
+- Join our [Discord](https://discord.gg/UfGNZJfAG6) to share feedback and feature requests