# MCP Server

The Spectora MCP Server lets you connect AI assistants — like Claude, ChatGPT, Cursor, and GitHub Copilot — directly to your Spectora account. The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that gives AI tools secure, structured access to your inspection business data.

Once connected, you can use natural language to work with your data. For example:

- "Which agents referred the most inspections this quarter, and what's their contact info?"
- "Compare my top 5 agents by inspection volume over the last 6 months"
- "Find all inspections in Austin, TX from the past 30 days that are still pending"
- "Show me all clients with inspections scheduled this week"

---

## Before You Begin

All you need is:

1. **A Spectora account** with company admin permission.
2. **An AI tool that supports MCP** — see below for setup guides covering popular tools.

---

## MCP Connection Details

**Server URL:** `https://connect.spectora.com/mcp`

**Transport:** Streamable HTTP

**Authentication:** OAuth (recommended) or API key — both covered in the [Setup Instructions](#setup-instructions) below.

---

## Setup Instructions

The MCP Server supports two authentication methods. Pick the one that fits, then follow your tool's guide.

### OAuth (recommended)

When you add the server, your AI tool opens a browser window where you sign in to Spectora and approve access. The connection then acts as **you** — the signed-in Spectora user — with access to the [available tools](#available-tools) below (all currently read-only).

:::note
The connection is tied to the profile you sign in with. If your active profile changes later, the connection may not pick up the change immediately. To apply it right away, disconnect and reconnect Spectora MCP Server in your AI tool.
:::

#### Claude (web and desktop)

1. Go to **Settings** -> **Connectors** and click **Add custom connector**
2. Configure the connector:
   - **Name:** Spectora
   - **MCP Server URL:** `https://connect.spectora.com/mcp`
3. Click **Add** and complete the Spectora sign-in when prompted

The steps are the same on [claude.ai](https://claude.ai) and in the Claude Desktop app. See [Anthropic's custom connector guide](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) if the menu layout has changed.

---

#### Claude Code

Run the following command in your terminal:

```bash
claude mcp add --transport http spectora https://connect.spectora.com/mcp
```

Then run `/mcp` inside Claude Code and select **spectora** — a browser window opens where you sign in to Spectora and approve access.

---

#### ChatGPT

1. Go to **Settings** -> **Plugins** and enable **Developer mode**
2. Add a plugin and configure:
   - **Name:** Spectora
   - **MCP Server URL:** `https://connect.spectora.com/mcp`
   - **Authentication:** OAuth
3. Enable the confirmation checkbox and click **Create**, then complete the Spectora sign-in when prompted

See [OpenAI's developer mode guide](https://developers.openai.com/api/docs/guides/developer-mode) if the menu layout has changed.

---

#### Cursor

1. Go to **Cursor Settings** -> **Tools & MCP** -> **New MCP Server**
2. Paste the following configuration:

```json
{
  "mcpServers": {
    "spectora": {
      "url": "https://connect.spectora.com/mcp"
    }
  }
}
```

3. Save the file — Cursor prompts you to sign in to Spectora and approve access
4. Verify that `spectora` appears as connected in the **Installed MCP Servers** panel

---

#### Other Tools

MCP is an open protocol supported by many clients. Refer to your client's documentation for specific connection steps, using the [MCP Connection Details](#mcp-connection-details) above. Most clients accept a configuration similar to this, and open a browser for you to sign in to Spectora:

```json
{
  "spectora": {
    "url": "https://connect.spectora.com/mcp"
  }
}
```

If your client doesn't support OAuth, see [API Key](#api-key) below.

---

### API Key

The better fit when nobody is around to sign in — automations, scripts, or tools that don't support browser sign-in. Create an API key [here](/settings/api-keys), then pass it via the `Authorization: Bearer YOUR_API_KEY` header, or via the `apiKey=YOUR_API_KEY` query parameter for tools that don't support custom headers.

:::note
The key is tied to the profile that created it, and stays that way — even if your active profile changes later, the key keeps using the original one.
:::

:::caution
Keep your API key secure — do not expose it in client-side code or public repositories. If you believe your key has been compromised, roll it immediately from the [API Keys](/settings/api-keys) page.
:::

:::tip
Some setups below use `npx`, which requires [Node.js](https://nodejs.org/) to be installed on your machine.
<br />
To verify everything is set up correctly, open your terminal and run `node --version` and `npx --version` — both should return a version number.
:::

#### Claude Desktop

:::caution{title="Windows users"}
- Make sure you are using a proper text editor like [Notepad++](https://notepad-plus-plus.org/) when editing `claude_desktop_config.json`.
- Use the Task Manager to fully quit the application and then restart it.
:::

1. Go to **Settings** -> **Developer** -> **Edit Config**
2. Open the `claude_desktop_config.json` file and paste the following configuration:

**macOS / Linux:**

```json
{
  "mcpServers": {
    "spectora": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://connect.spectora.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}
```

**Windows:**

```json
{
  "mcpServers": {
    "spectora": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "mcp-remote",
        "https://connect.spectora.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}
```

3. Save the file and restart Claude Desktop
4. Verify that `spectora` appears as a connected MCP server

---

#### Claude Code

Pass the header on the command line:

```bash
claude mcp add --transport http spectora https://connect.spectora.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
```

---

#### ChatGPT

Follow the [ChatGPT setup steps](#chatgpt) above, but set the **MCP Server URL** to `https://connect.spectora.com/mcp?apiKey=YOUR_API_KEY` and **Authentication** to **No Auth**.

---

#### Cursor

1. Go to **Cursor Settings** -> **Tools & MCP** -> **New MCP Server**
2. Paste the following configuration:

**macOS / Linux:**

```json
{
  "mcpServers": {
    "spectora": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://connect.spectora.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}
```

**Windows:**

```json
{
  "mcpServers": {
    "spectora": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "mcp-remote",
        "https://connect.spectora.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}
```

3. Save the file and verify that `spectora` appears as connected in the **Installed MCP Servers** panel

---

#### Other Tools

Clients that support custom headers accept a configuration like this:

```json
{
  "spectora": {
    "url": "https://connect.spectora.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}
```

---

## Available Tools

The MCP Server exposes the following tools:

| Resource | Tool | Description | API |
|----------|------|-------------|-----|
| Agents | `list-connections-v2` | Browse and filter your agents | [List Agents](/api/agents#list-agents) |
| Agents | `get-connection-v2` | Get details of a specific agent | [Get Agent](/api/agents#get-an-agent) |
| Agent Stats | `list-connection-stats-v2` | Browse agents enriched with inspection statistics | [List Agent Stats](/api/agent-stats#list-agent-stats) |
| Clients | `list-contacts-v2` | Browse and filter your clients | [List Clients](/api/clients#list-clients) |
| Clients | `get-contact-v2` | Get details of a specific client | [Get Client](/api/clients#get-a-client) |
| Inspection Attachments | `list-inspection-attachments-v2` | Browse and filter inspection attachments | [List Inspection Attachments](/api/inspection-attachments#list-inspection-attachments) |
| Events | `list-events-v2` | Browse events, filterable by inspection | [List Events](/api/events#list-events) |
| Events | `get-event-v2` | Get details of a specific event | [Get Event](/api/events#get-an-event) |
| Inspections | `list-inspections-v2` | Browse and filter your inspections | [List Inspections](/api/inspections#list-inspections) |
| Inspections | `show-inspection-v2` | Get details of a specific inspection | [Get Inspection](/api/inspections#get-an-inspection) |

---

## Troubleshooting

- **Authentication errors (OAuth)** — Disconnect and reconnect Spectora MCP Server in your AI tool to restart the sign-in flow.
- **Authentication errors (API key)** — Verify your API key is valid and has not expired. You can manage your keys [here](/settings/api-keys).
- **`npx` command not found** — Install [Node.js](https://nodejs.org/), which includes `npx`. Only needed for the `mcp-remote` API key setup.
- **Tools not appearing** — Restart your AI tool after making configuration changes.