Skip to main content

MCP Tool Concepts

What is MCP?#

The Model Context Protocol (MCP) is an open standard that enables AI Large Language Models (LLMs) to seamlessly connect with external systems. MCP provides a unified way for LLMs to interact with tools, data sources, and workflows, similar to how REST APIs standardise client–server communication. Instead of every AI client inventing its own integration mechanism, MCP defines a common contract: a server advertises a set of tools, each with a name, a description, and an input schema, and a client can discover those tools and call them on demand during a conversation.

The Twinit AI Service supports MCP and can act as an MCP server. This means external MCP clients such as Cursor, Claude, and GitHub Copilot can connect directly to Twinit and call tools that operate on your platform data.

System MCP Tools vs Custom MCP Tools#

In the AI Service there are two kinds of MCP Tools.

System MCP Tools#

System MCP Tools are generated automatically from the Platform API package. Every read operation across the platform services, such as the Item Service, File Service, and Notification Service, is eligible to be exposed as a System MCP Tool. They are identified by the _type property set to system_mcp_tool. Examples include tools that get a file version count, retrieve graphics permissions, or fetch a notification group.

System MCP Tools require no coding, you simply choose which ones to expose. They are perfect for giving an AI client safe, read-only access to standard platform data.

Custom MCP Tools#

Custom MCP Tools are tools you create. They are identified by the _type property set to user_mcp_tool. A Custom MCP Tool references a backend script in the Item Service. When the tool is invoked through MCP, the AI Service executes the referenced script via the ScriptWorker and returns the result to the calling client.

Custom MCP Tools are the focus of this course. They let you encapsulate your own business logic, custom queries, validation, and data transformations, behind a single, well-described tool that any MCP client can call.

Anatomy of a Custom MCP Tool#

A Custom MCP Tool brings together two pieces:

  • A backend script function – the actual logic that runs. It receives the tool's input arguments, calls the platform APIs (for example the Item Service to query a collection), and returns a result.
  • A tool configuration – the metadata that describes the tool to the AI model. This includes a clear name, a detailed description that tells the model what the tool does and when to use it, an input schema that validates the arguments the tool receives, and a reference to the backend script and function that backs the tool.

When an MCP client invokes the tool, the request flows through the system as follows:

  1. The MCP client (Cursor, Claude, or Copilot) connects to the AI Service MCP endpoint over streamable HTTP, authorised with an API key.
  2. The AI Service matches the call to your Custom MCP Tool configuration and validates the input against its schema.
  3. The AI Service runs the referenced Item Service backend script via the ScriptWorker.
  4. The script queries the Computer Science course data and returns a result back up the chain to the client.

The description and the schema are the most important parts of the configuration, because they are how the AI model understands the tool. A vague description or a loose schema makes it harder for the model to decide when and how to call the tool. A clear, specific description and a well-typed schema, with a meaningful description on each field, let the model use the tool reliably with minimal prompting.

The AI Service as an MCP Server#

Once you have created your tools, the AI Service exposes them over a streamable HTTP MCP endpoint. External MCP clients connect to this endpoint, discover the available tools, and call them automatically during conversations. Access is authorised using a one-time API key issued by the Passport Service, so only authorised clients can reach your tools.

You can also narrow which tools a client sees. An optional MCP Tool Filter is a saved, reusable rule-set, for example "only File and Item Service system tools", that you reference when configuring the MCP server connection. This is useful when you want to expose a focused, curated set of tools rather than everything in the namespace.

You can read more about MCP Tools and the AI Service MCP server on twinit.dev.

What we will build#

In the next lessons we will:

  1. Create a Custom MCP Tool that wraps the getCourseByTitle backend script, complete with a description and an input schema.
  2. Expose and consume the tool by configuring an MCP client (Cursor) to connect to the AI Service MCP endpoint, then ask natural-language questions answered from the Computer Science course data.

Each lesson provides both a Code workflow and an IDE Extension workflow, so you can follow whichever approach you prefer.