Updated Nov 1, 2026

Using Custom Types with MCP and AI

What you'll learn

• How Custom Types are exposed to AI agents and external MCP clients
• How agents discover your types and write records against them
• When to add MCP hints to guide the agent's behaviour

AutoTalk's MCP server lets any LLM client — Claude Desktop, Cursor, ChatGPT, a custom agent — read and write your company's data through a uniform tool interface. Custom Types are exposed through that same interface.

What agents get for free

When you create a Custom Type, the MCP server automatically exposes it. An agent connected to your AutoTalk workspace with a valid API key can:

• Discover your types with list_custom_types
• Read the shape of a type with get_custom_type_definition
• Query, create, update, delete records using the generic query_documents, get_document, create_document, update_document, delete_document tools with the type name ct:<slug>
• Author new Custom Types with create_custom_type (plus update_custom_type and delete_custom_type to evolve or retire them) — these three require the Custom types permission (org.types:admin) on the key

You do not have to configure anything extra — as soon as the type exists in your company, it's available to any authenticated MCP client.

How an agent uses your type

Imagine you've created a type with slug helpdesk_tickets. An agent asking to "file a ticket for customer Alice" would:

1. Call list_custom_types and find helpdesk_tickets.
2. Call get_custom_type_definition to see the field shape and required values.
3. Call create_document with type: "ct:helpdesk_tickets" and the filled-in fields.

note

Slugs that match built-in collection names (contacts, messages, support_tickets, …) are reserved — create_custom_type rejects them with reserved_slug. Slugs are also immutable after creation, so pick carefully.

Follow-up questions ("show me all open high-priority tickets") translate into query_documents calls.

Writing good MCP hints

When you create or edit a Custom Type, the MCP hints field is where you tell the agent how to use your type. Agents see these hints alongside the type definition.

Good hints look like:

• "Always set status when creating a lead."
• "Link to a contact via contactId when the lead came from a known conversation."
• "When flipping status to resolved, also set resolvedAt to the current time."
• "Priority defaults to 3. Only raise it if the user explicitly says the issue is urgent."

Keep them short and imperative. Think of them as rules that would go in an agent's system prompt.

Writing a good purpose

The Purpose field on the type definition is equally important. It tells the agent when to reach for your type in the first place. Treat it like a handoff note:

"Track sales leads from first touch through qualification. When the user mentions lead generation, opportunities, prospects, or the sales pipeline, fetch or create a record in this type instead of using the built-in Contacts entity."

A clear purpose plus a few targeted hints improves how agents route requests to your Custom Type.

Authoring a Custom Type from an agent

You don't have to define Custom Types through the UI. An agent whose API key carries the Custom types permission (org.types:admin) can call create_custom_type directly, for example after a conversation like:

"I need to track our company's training courses — course name, start date, instructor, capacity, enrolled count. Create that."

The agent translates that into a create_custom_type call with the right field list. You'll see the new type appear in your sidebar afterwards, ready to use.

When a type definition or patch includes CEL labels, visibility or preview expressions, include top-level celSchemaGeneration: "4" in the create_custom_type/update_custom_type call. Keep it outside the stored patch or field definition. Generic document write/validation tools require the same argument when they submit CEL source. Ordinary record values are data; a key named expr alone does not make them executable CEL. HTTP source writes and validation send X-Autotalk-Cel-Schema: 4, also for nonbrowser callers.

Limits and safety

• Over MCP, create_custom_type, update_custom_type and delete_custom_type require the Custom types permission (org.types:admin) on the API key — the broader Account administration and Full access permissions include it. A key without it is refused at the MCP scope gate before the tool runs, and the denial is recorded in the audit trail. The read-only pair — list_custom_types and get_custom_type_definition — needs only data:read. The owner-only restriction (requireOwner) applies to the in-app UI and /data routes, not to MCP: a key that does carry org.types:admin faces no further owner check. See Permissions.
• Agents cannot define new document actions / functions on Custom Types — Custom Types are data-only in this release.
• All CRUD is tenant-isolated — an MCP client can only ever touch your own company's records. However, MCP clients operate at owner level: the per-role access lists you configure on a Custom Type (Type access) restrict your employees in the app, not MCP/API-key clients.
• Automations react to your type's records: workflows and outbound webhooks with a hook trigger on model ct:<slug> fire on record create/update/delete. Manage webhooks through generic MCP/API document tools with type: "webhooks"; writes require org.webhooks:admin.

Example: linking to built-in entities

Cross-reference fields let your Custom Type plug into the rest of AutoTalk. For example a helpdesk_tickets type with these reference fields:

Field	Points to	Effect
contactId	contacts (built-in)	Links the ticket to a contact record
assignedTo	employees (built-in)	Shows the assigned teammate
relatedLeadId	ct:leads (another Custom Type)	Links back to the originating lead

Agents (and the UI) can traverse these references — clicking the contactId opens the contact page, for example.

Next steps

• API tokens — create the API key an MCP client will use
• MCP servers — full reference for the MCP endpoint