# MCP Server Integration

> Connect AI coding assistants like Cursor, Claude Code, and Claude Desktop to your Infa design system using the Model Context Protocol (MCP).

Source: https://infa.ai/docs/mcp

The Infa MCP Server allows AI coding assistants to access your design system data directly. This enables AI tools to understand your components, screens, design tokens, and documentation when helping you write code. Authentication is handled securely through **OAuth 2.1**, so no API keys are needed.

## Overview

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external data sources. Infa's MCP server provides read access to your design system, enabling AI tools to:

- List and search your boards
- Access component information and screenshots
- Retrieve design tokens and their values
- Read documentation and papers
- Search across all content types

**Endpoint**: `https://infa.ai/api/mcp`

## Supported AI Tools

- **Cursor**: AI-powered code editor with MCP support
- **Claude Code**: Anthropic's Claude in your terminal
- **Claude Desktop**: Claude desktop app with MCP

## Quick Setup

### One-Click Installation (Easiest)

For the smoothest experience, use our one-click installer in your [Profile Settings](https://infa.ai/profile?tab=integrations):

1. Go to [Profile → Integrations → MCP Server Integration](https://infa.ai/profile?tab=integrations)
2. Click **"Add to Cursor"** for instant installation, or
3. Copy the configuration for Claude Code or Claude Desktop

### Manual Configuration

If you prefer manual setup, here's how to configure each tool:

#### Cursor IDE

Add this to your Cursor MCP configuration (Settings → Features → MCP):

```json title="cursor-mcp.json"
{
    "mcpServers": {
        "infa": {
            "url": "https://infa.ai/api/mcp"
        }
    }
}
```

When you first use an Infa tool, Cursor will open a browser window for you to log in and authorize access.

#### Claude Code

Add this to your `~/.claude.json` config file:

```json title="~/.claude.json"
{
    "mcpServers": {
        "infa": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://infa.ai/api/mcp"]
        }
    }
}
```

After saving, restart Claude Code with `claude` or use `/mcp` to verify the connection. You'll be prompted to authorize access in your browser.

#### Claude Desktop

Add this to your Claude Desktop MCP configuration file (`.cursor/mcp.json`):

```json title=".cursor/mcp.json"
{
    "mcpServers": {
        "infa": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://infa.ai/api/mcp"]
        }
    }
}
```

### How Authentication Works

Infa uses **OAuth 2.1 with PKCE** for MCP authentication, managed by Supabase. This provides:

1. **Secure login** - You authenticate with your Infa account (Google or email)
2. **Explicit consent** - You approve which AI tool can access your data
3. **Row Level Security** - Data access is automatically scoped to your account
4. **Automatic token refresh** - No need to manually manage tokens
5. **Revocable access** - You can revoke access anytime from your profile

When you first connect an MCP client:

1. The AI tool discovers Infa's OAuth endpoints automatically via `/.well-known/oauth-authorization-server`
2. A browser window opens for you to log in to Infa
3. You see a consent screen showing which app is requesting access and what data it can access
4. After approval, the AI tool receives secure OAuth tokens
5. Tokens are issued by Supabase with proper claims for Row Level Security enforcement
6. Tokens refresh automatically - no manual intervention needed

**No API keys needed** OAuth 2.1 authentication is handled automatically and securely. You don't need to generate or manage API keys for MCP access.

## Available Tools

Once connected, your AI assistant will have access to these tools:

### infa.listBoards

List all boards accessible to your account.

**Parameters:**

- `starredOnly` (boolean, optional): Only return bookmarked boards

**Example prompt:** _"List my Infa boards"_

### infa.exportBoard

Export complete board data including screens, components, tokens, papers, and labels.

**Parameters:**

- `boardId` (string, required): The UUID of the board
- `include` (object, optional): Specify which data to include
    - `screens` (boolean)
    - `components` (boolean)
    - `tokens` (boolean)
    - `papers` (boolean)
    - `labels` (boolean)

**Example prompt:** _"Export the complete data from my Design System board"_

### infa.getBoardPages

Get screens from a specific board with optional search filters.

**Parameters:**

- `boardId` (string, required): The UUID of the board
- `searchTitle` (string, optional): Filter by page title
- `searchUrl` (string, optional): Filter by page URL
- `limit` (number, optional): Maximum results (1-100)

**Example prompt:** _"Show me all screens containing 'dashboard' in my board"_

### infa.getBoardComponents

Get components with optional title and label filters.

**Parameters:**

- `boardId` (string, required): The UUID of the board
- `searchTitle` (string, optional): Filter by component title
- `labels` (array, optional): Filter by label names
- `limit` (number, optional): Maximum results (1-100)

**Example prompt:** _"Find all button components labeled 'primary'"_

### infa.getDesignTokens

Get all design token collections and their values.

**Parameters:**

- `boardId` (string, required): The UUID of the board

**Example prompt:** _"What are the color tokens in my design system?"_

### infa.getBoardPapers

Get all documentation papers from a board.

**Parameters:**

- `boardId` (string, required): The UUID of the board

**Example prompt:** _"Show me the documentation for this board"_

### infa.searchBoard

Search across all content types in a board.

**Parameters:**

- `boardId` (string, required): The UUID of the board
- `query` (string, required): Search query
- `types` (array, optional): Content types to search (`page`, `component`, `token`, `paper`)
- `limit` (number, optional): Maximum results (1-50)

**Example prompt:** _"Search for anything related to 'navigation' in my board"_

## Example Workflows

### Getting Component Information for Code

```
You: "I need to implement a button component. Can you check what button
     styles we have in our Infa design system?"

AI: [Uses infa.getBoardComponents to find button components]
    "I found 3 button variants in your design system:
    - Primary Button: Used for main actions
    - Secondary Button: Used for secondary actions
    - Ghost Button: Used for tertiary actions

    Here's the code based on your component specifications..."
```

### Using Design Tokens

```
You: "What's our primary brand color? I need to use it in this component."

AI: [Uses infa.getDesignTokens to fetch color tokens]
    "Your primary brand color is defined as:
    - Token: --color-primary
    - Value: #0f62fe

    You should use `var(--color-primary)` in your CSS."
```

### Checking Component Usage Across Screens

```
You: "Which screens use our Header component?"

AI: [Uses infa.searchBoard to find Header references]
    "The Header component appears on 12 screens including:
    - Homepage
    - Dashboard
    - Settings
    ..."
```

## Authentication

The MCP server uses **OAuth 2.1 with PKCE**, managed by Supabase, with these features:

- **Standards-compliant** - Full OAuth 2.1 with PKCE and OpenID Connect support
- **Automatic discovery** - MCP clients discover auth endpoints automatically
- **Dynamic client registration** - Supported clients register automatically (RFC 7591)
- **Row Level Security** - Your data access is automatically scoped to your user account
- **Database-enforced security** - RLS policies enforce permissions at the database level
- **Token refresh** - Tokens are refreshed automatically in the background
- **Secure endpoints** - All OAuth endpoints use HTTPS with proper security headers

### How Your Data is Protected

When you approve MCP access:

1. **Supabase issues a JWT token** with your user ID and proper claims
2. **RLS policies automatically enforce** access restrictions based on your account
3. **You can only see data you own** - even if someone compromises a token
4. **All queries are scoped** - the database layer enforces your permissions

### Revoking Access

To revoke an AI tool's access to your Infa data:

1. Go to [Profile Settings](https://infa.ai/profile?tab=integrations)
2. Find the **Connected Applications** section
3. Click **Revoke** next to the application you want to disconnect

Once revoked, that application can no longer access your Infa data.

## Troubleshooting

### "Unauthorized" Error

- Make sure you completed the OAuth flow in your browser
- Check that you approved access on the consent screen
- Try disconnecting and reconnecting the MCP server

### Browser Doesn't Open for Authentication

- Ensure your AI tool supports OAuth (most modern MCP clients do)
- Check if there's a popup blocker preventing the auth window
- Try manually navigating to `https://infa.ai/login` and logging in first

### Tools Not Appearing

- Restart your AI tool after adding the MCP configuration
- Check the MCP server logs for connection errors
- Verify the endpoint URL is correct: `https://infa.ai/api/mcp`

### Empty Results

- Confirm you have boards created in your Infa account
- Check that you're using the correct board ID (UUID format)
- Verify your account has access to the requested board

## Security

Infa's MCP integration uses multiple layers of security:

### Token Security

- **OAuth 2.1 tokens** are issued by Supabase with proper claims
- Tokens include your user ID and authentication context
- Tokens expire and are automatically refreshed
- You can revoke tokens at any time from your profile

### Data Access Control

- **Row Level Security (RLS)** enforces permissions at the database level
- Access is automatically scoped to data you own
- Related data (screens, components, tokens) respects your board permissions
- Even if a token is compromised, attackers can only see your data

### Transport Security

- All communication uses HTTPS with proper TLS certificates
- OAuth discovery endpoints are protected from tampering
- Authorization codes are single-use and short-lived
- Tokens are never logged or stored insecurely

### Best Practices

- Revoke access for tools you no longer use
- Regularly review connected applications in your profile
- Don't share your Infa credentials with AI tools - use OAuth instead
- Report any security concerns to [security@infa.ai](mailto:security@infa.ai)

## Build Apps and App Blocks over MCP

The MCP server is also how AI agents build [App Blocks](https://infa.ai/docs/app-blocks): HTML mini-apps that render live on Infa documents and canvases, or as an [App](https://infa.ai/docs/apps), a page of their own. Once connected, have your agent call the `infa_appBlockGuide` tool to fetch the full block contract (the MCP Apps SDK, theme, state, integration data and what a block may load), then register and iterate with `infa_registerAppBlock`, `infa_appBlockPreview` and `infa_updateAppBlock`, turn the block into an App with `infa_createPaper` (`type: "app"`), and share it with `infa_publishAppBlock`.

In a chat that renders MCP Apps (Claude desktop, ChatGPT, VS Code), `infa_openApp` opens an App, or a block type, right in the conversation, with its saved state and its connections.

See [Building Apps and App Blocks](https://infa.ai/docs/building) for the complete workflow, including a ready-to-paste agent prompt.

## Next Steps

- [Create your first Board](https://infa.ai/docs/boards)
- [Build Apps and App Blocks](https://infa.ai/docs/building)
- [Explore the External API](https://infa.ai/docs/api)
- [Organize components, screens and design tokens with Labels](https://infa.ai/docs/labels)
