> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perceptron.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> AI agents can interact with Perceptron's vision capabilities through our MCP server.

The Perceptron Vision MCP Server enables AI assistants to access Perceptron's powerful vision-language capabilities directly within their workflows. Built on the [Model Context Protocol](https://modelcontextprotocol.io/), it gives your agents the ability to see and reason about images and videos — captioning, object detection, OCR, and visual Q\&A — without writing any integration code.

With native local file support, your agent can point to any local image or video — the server handles the rest, uploading it directly to the Perceptron Vision MCP Server.

## Before you begin

You need the following to use the MCP server:

* **Perceptron API key** — to authenticate requests from the MCP server.
* **Node.js (LTS)** — required to run the MCP server package via `npx`.

<CardGroup cols={2}>
  <Card title="Create an API key" icon="key" href="https://platform.perceptron.inc/">
    Get your key from the Perceptron platform
  </Card>

  <Card title="Join Discord" icon="discord" href="https://discord.gg/fgBeaACQzE">
    Get help and see what others are building
  </Card>
</CardGroup>

## Quick setup

Get started instantly with one-click installers:

<CardGroup cols={2}>
  <Card title="Install in Cursor" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 466.73 532.09"><path d="M457.43 125.94 244.42 2.96a22.127 22.127 0 0 0-22.12 0L9.3 125.94C3.55 129.26 0 135.4 0 142.05v247.99c0 6.65 3.55 12.79 9.3 16.11l213.01 122.98a22.127 22.127 0 0 0 22.12 0l213.01-122.98c5.75-3.32 9.3-9.46 9.3-16.11V142.05c0-6.65-3.55-12.79-9.3-16.11h-.01Zm-13.38 26.05L238.42 508.15c-1.39 2.4-5.06 1.42-5.06-1.36V273.58c0-4.66-2.49-8.97-6.53-11.31L24.87 145.67c-2.4-1.39-1.42-5.06 1.36-5.06h411.26c5.84 0 9.49 6.33 6.57 11.39h-.01Z" fill="currentColor"/></svg>} href="https://cursor.com/en/install-mcp?name=perceptron&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwZXJjZXB0cm9uLWFpL21jcC1zZXJ2ZXJAbGF0ZXN0Il0sImVudiI6eyJQRVJDRVBUUk9OX0FQSV9LRVkiOiIifX0=" />

  <Card title="Install in VS Code" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><path d="M70.912 99.572a6.193 6.193 0 0 0 4.96-.191l20.588-9.958a6.285 6.285 0 0 0 3.54-5.661V16.239a6.286 6.286 0 0 0-3.54-5.662L75.873.62a6.2 6.2 0 0 0-7.104 1.216L29.355 37.98l-17.168-13.1a4.146 4.146 0 0 0-5.318.238l-5.506 5.035a4.205 4.205 0 0 0-.004 6.194L16.247 50 1.36 63.654a4.205 4.205 0 0 0 .004 6.194l5.506 5.034a4.145 4.145 0 0 0 5.318.238l17.168-13.1L68.77 98.166a6.205 6.205 0 0 0 2.143 1.407Zm4.103-72.39L45.11 50 75.015 72.82V27.18Z" fillRule="evenodd" fill="#007ACC"/></svg>} href="https://vscode.dev/redirect/mcp/install?name=perceptron&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40perceptron-ai%2Fmcp-server%40latest%22%5D%2C%22env%22%3A%7B%22PERCEPTRON_API_KEY%22%3A%22%22%7D%7D" />
</CardGroup>

Or follow the manual setup steps below.

## Manual setup

<Tabs>
  <Tab title="Claude Code">
    Run the following command (recommended):

    ```bash theme={null}
    claude mcp add perceptron -e PERCEPTRON_API_KEY=YOUR_API_KEY -- npx -y @perceptron-ai/mcp-server@latest
    ```
  </Tab>

  <Tab title="Codex">
    Run the following command:

    ```bash theme={null}
    codex mcp add perceptron --env PERCEPTRON_API_KEY=YOUR_API_KEY -- npx -y @perceptron-ai/mcp-server@latest
    ```
  </Tab>

  <Tab title="Cursor">
    Add the following to `.cursor/mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "perceptron": {
          "command": "npx",
          "args": ["-y", "@perceptron-ai/mcp-server@latest"],
          "env": {
            "PERCEPTRON_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other Clients">
    Use the configuration below for your client. The config file location varies by client:

    | Client             | Config File                             |
    | ------------------ | --------------------------------------- |
    | Cursor             | `~/.cursor/mcp.json`                    |
    | VS Code            | `.vscode/mcp.json`                      |
    | Claude Desktop     | `claude_desktop_config.json`            |
    | Google Antigravity | `~/.gemini/antigravity/mcp_config.json` |

    For all clients except VS Code, use the `mcpServers` format:

    ```json theme={null}
    {
      "mcpServers": {
        "perceptron": {
          "command": "npx",
          "args": ["-y", "@perceptron-ai/mcp-server@latest"],
          "env": {
            "PERCEPTRON_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    For **VS Code**, use the `servers` format instead:

    ```json theme={null}
    {
      "servers": {
        "perceptron": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@perceptron-ai/mcp-server@latest"],
          "env": {
            "PERCEPTRON_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Replace `YOUR_API_KEY` with your actual Perceptron API key.

## Available tools

The MCP server provides four tools that give your AI agent vision capabilities:

<CardGroup cols={2}>
  <Card title="caption" icon="image">
    Generate a natural-language caption for an image or video. Ideal for describing screenshots, photos, clips, or any visual content your agent encounters.
  </Card>

  <Card title="detect" icon="object-group">
    Detect and locate objects in an image or video. Returns bounding boxes and labels for identified objects — perfect for analyzing UI mockups, counting items, or understanding scene composition.
  </Card>

  <Card title="ocr" icon="font">
    Extract text from an image using optical character recognition. Use it to read receipts, documents, signs, or any image containing text.
  </Card>

  <Card title="question" icon="comment-question">
    Ask a question about an image or video and get an answer. Great for visual Q\&A tasks like identifying colors, reading labels, or understanding context in a photo or clip.
  </Card>
</CardGroup>

Each tool works directly with local image and video files — no need to upload or host them. The MCP server reads files locally and sends them directly to the API, avoiding large base64 payloads in the conversation context for fast, lightweight processing. Results include text responses and optional grounded geometry (points, boxes, or polygons) on a normalized [0-1000 coordinate system](/perceptron-mk1/concepts/coordinates).

<Note>
  See the [Models](/perceptron-mk1/models) tab for all available model IDs, or call `list_resources` at runtime.
</Note>

## Example usage

Once connected, your AI agent can call Perceptron tools directly. Here are some example prompts:

* **"Caption this screenshot"** — the agent calls `caption` and returns a description
* **"Find all the buttons in this UI mockup"** — the agent calls `detect` with the relevant classes
* **"Read the text from this receipt"** — the agent calls `ocr` to extract structured text
* **"What color is the car in this photo?"** — the agent calls `question` with your query

<Note>
  For troubleshooting and additional details, visit our [GitHub repository](https://github.com/perceptron-ai-inc/mcp-server). Reach out to [Perceptron support](mailto:support@perceptron.inc) or join our [Discord](https://discord.gg/fgBeaACQzE) if you have questions.
</Note>