Connect the Trackunit MCP

The Trackunit MCP (Model Context Protocol) server gives AI coding agents such as Cursor and Claude Code direct access to the tools they need while building an IrisX App:

• GraphQL: inspect the Trackunit GraphQL schema and validate queries before you run codegen.
• Design System: list the available components and fetch usage code, so the agent uses real Trackunit components instead of guessing.

Workspaces created with npx @trackunit/create-iris-app-workspace (or refreshed with npx nx g @trackunit/iris-app:ai-agent-sync) already contain the server configuration. You only need to authenticate once.

Server configuration

The server is registered under the name trackunit in both files below:

File	Used by
.cursor/mcp.json	Cursor
.mcp.json	Claude Code and other MCP-capable agents

{
  "mcpServers": {
    "trackunit": {
      "type": "http",
      "url": "https://mcp.trackunit.ai/mcp"
    }
  }
}

If you use another MCP-capable agent, add the same URL as a remote (Streamable HTTP) server.

Requirements

• An IrisX account.
• The iris.app.developer permission on your account (see permissions). Without it, the design-system tools and query validation are not available to you.

The connection uses OAuth. Your agent can only see what your Trackunit user is allowed to see.

Connect

Cursor

1. Open the workspace in Cursor.
2. Open Cursor Settings and go to MCP (Cmd+, on macOS, Ctrl+, on Windows/Linux).
3. Find trackunit, enable it and click Connect.
4. Complete the sign-in in your browser.

Claude Code

1. Start Claude Code in the workspace and approve the project MCP servers when asked.
2. Run /mcp, select trackunit and choose Authenticate.
3. Complete the sign-in in your browser.

After changing .mcp.json, restart the agent so it picks up the change.

For Claude.ai, ChatGPT and Microsoft Copilot, see Connect Trackunit IrisX MCP in the Help Center.

Available tools

Tool	Use it for
explore_introspect_gql_schema	Explore types, fields and operations in the Trackunit GraphQL schema
explore_validate_gql_query	Check a query against the schema before running it
explore_get_design_system_components	List the Trackunit design system components
explore_get_design_system_code	Get usage code for a component

Which tools your agent can use depends on your permissions and on the agent client.

When the MCP is not connected

An agent that cannot use the MCP tools should not stop or invent components. The generated AGENTS.md in your workspace tells it to check which tools are available first and use these public fallbacks otherwise:

• UI components: fetch the component catalog at https://design.iris.trackunit.com/llms.txt, then a component page at https://design.iris.trackunit.com/ai?storyId=<id>. This needs no authentication.
• GraphQL: use the GraphQL API documentation and the graphql skill in your workspace (.agents/skills/graphql) to generate typed hooks with Nx.

Troubleshooting

The server shows as not connected or red

You have not completed the sign-in yet. Connect it from the agent's MCP settings as described above. Until then your agent works with the fallbacks.

The tools are missing after signing in

• Check that your user has the iris.app.developer permission.
• Restart the agent so it reloads the tool list.

Sign-in fails

Make sure you sign in with the IrisX user that has developer access. If you do not have it, ask an administrator of your Trackunit account.