Updated Aug 4, 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)

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 with a valid API key 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.

Limits and safety

• Over MCP, create_custom_type, update_custom_type, and delete_custom_type are gated only by a valid company API key, which grants full tenant access — the owner-only restriction (requireOwner) applies to the in-app UI and /data routes, not to MCP. Treat any API key that can reach the MCP endpoint as able to author and delete Custom Types.
• 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. (Webhook management itself stays in-app only — it is not exposed over MCP.)

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