Craft.io MCP server and REST API: what's the difference?

Craft.io offers two ways to connect external tools and AI assistants to your product data: the MCP server and the Public REST API. They are not competing options - they are designed for different contexts. Understanding the distinction helps you choose the right approach from the start, or combine both where it makes sense.

In this article:

The REST API is a standard HTTP API built for programmatic integration. It works in any environment - no AI assistant required - and is well-suited for scheduled syncs, BI pipelines, custom applications, and any workflow where a developer is building a structured integration with full control over behavior.
​

The MCP server is built specifically for AI assistant workflows. It connects LLMs like Claude, ChatGPT, and Cursor directly to your Craft.io data, and includes features designed to make those AI interactions faster, safer, and more accurate.

Both options are valid. Many teams use both - the REST API for automated pipelines and the MCP server for AI-assisted work.

With the REST API: You have full visibility into the API structure. Developers can explore endpoints, parameters, and field definitions through the API documentation and build exactly the behavior they need. This level of control is an advantage when you are building a precise, long-running integration.
​

With the MCP server: The MCP tools are pre-built with an understanding of Craft.io's data model - item types, hierarchy, terminology, and available fields. The AI model does not need to be told what exists or how data is structured; that knowledge is already embedded in the tools. This means an AI assistant can work with your Craft.io data accurately from the first interaction, without requiring a developer to document the data model separately.

With the REST API: Your integration handles the API token directly - passing it in request headers, storing it securely, and managing rotation. This gives you full control over how credentials are managed within your system.
​

With the MCP server: Authentication is handled by the MCP layer. Every MCP connection is also tied to a specific Craft.io user and inherits their existing permissions, with a full audit trail of which user performed which action. For teams with strict governance requirements, this traceability is a meaningful advantage.

With the REST API: Responses are raw JSON. For developer integrations, this is the right format - structured, predictable, and easy to parse programmatically. Your code handles the shape of the data.
​

With the MCP server: Responses can be returned in formats optimized for AI consumption - including markdown, flat/columnar output, and field-selected responses that return only what a specific workflow needs. For AI workloads where every token in the context window matters, this reduces waste and keeps interactions efficient.

With the REST API: Standard HTTP status codes are returned. Your integration logic handles error interpretation and retry behavior. This gives developers full control over how errors are surfaced and acted on.
​

With the MCP server: Errors are returned in a way the AI model can interpret and act on without additional handling logic. Access scope - which workspaces and portfolios the agent can reach - is enforced at the MCP layer rather than managed by the agent. This reduces the risk of an AI workflow touching data it should not.

With the REST API: Lookups typically require internal numeric IDs. This is consistent and reliable for developer integrations that maintain their own ID mapping, and it is what most programmatic workflows are built on.
​

With the MCP server: Items can be looked up using short IDs (like CRK-5987) that resolve account-wide without needing a workspace ID. Keyword search spans title and description. For AI workflows where users are referencing items by name or ticket number in natural language, this removes a common friction point.

Both options can coexist within the same organization. There is no requirement to choose one permanently.

Now that you know which approach fits your use case, here is where to go next.

​Start connecting your AI assistant

If you are using the MCP server, the next step is connecting it to your AI tool of choice. See Introduction to the Craft.io MCP server for an overview of what you can do, then follow the setup guide for your specific tool.

Explore the REST API

If you are building a programmatic integration, the Craft.io public API reference covers available endpoints, authentication, and supported operations for the Core Platform and Feedback Portal.