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

# How to Set Up the MCP Server

> Configure PlaneConnection's Model Context Protocol (MCP) server to connect AI agents like Claude, CopilotKit, and other MCP-compatible clients to your flight operations data.

<Warning>
  This feature requires **administrator** or **workspace owner** permissions. Changes made here
  affect all users in your workspace.
</Warning>

PlaneConnection's MCP server is a standalone service that implements
the [Model Context Protocol](https://modelcontextprotocol.io), exposing
a comprehensive set of aviation tools across all platform modules. AI agents
connect to the server over HTTP and interact with your flight operations,
safety management, and FBO data using structured tool calls.

By the end of this guide you will have generated a service API key, configured
your AI agent to connect to the MCP server, verified the connection, and
scoped the agent's access to a specific workspace.

<Info>
  **Who should read this:** Workspace administrators who want to connect AI assistants (Claude
  Desktop, VS Code with Copilot, custom MCP clients) to their PlaneConnection data. You need the
  **Admin** role and access to your workspace's **Settings > Integrations** page.
</Info>

## Prerequisites

* An active PlaneConnection workspace with the **Admin** role.
* An MCP-compatible AI client (Claude Desktop, Claude Code, VS Code with
  Copilot, or any client supporting the MCP specification).

## Generate a service API key

<Steps>
  ### Step 1: Navigate to Integrations

  From the main navigation, go to **Settings > Integrations**. Select the
  **API Keys** tab.

  ### Step 2: Create a new API key

  Click **Create API Key**. Enter a descriptive name (e.g., "Claude Desktop MCP")
  and select the scope:

  | Scope          | Description                                                            |
  | -------------- | ---------------------------------------------------------------------- |
  | **Read-only**  | The agent can query data but cannot create, update, or cancel records. |
  | **Read-write** | The agent can invoke both read-only and destructive tools.             |

  <Warning>
    Read-write keys allow the AI agent to create trips, submit safety reports, modify crew
    assignments, and cancel reservations. Only grant this scope if you trust the agent's confirmation
    workflow. Start with read-only and upgrade later if needed.
  </Warning>

  ### Step 3: Copy the API key

  Copy the generated key immediately. It is shown only once. Store it securely
  \-- you will need it when configuring your AI client.
</Steps>

## Connect your AI client

<Tabs>
  <Tab title="Claude Desktop">
    Add the following to your Claude Desktop MCP configuration file
    (`~/.claude/claude_desktop_config.json` on macOS/Linux, or
    `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

    ```json theme={}
    {
      "mcpServers": {
        "planeconnection": {
          "url": "https://mcp.planeconnection.com/mcp",
          "headers": {
            "X-API-Key": "your-api-key-here",
            "X-Workspace-ID": "your-workspace-id"
          }
        }
      }
    }
    ```

    Restart Claude Desktop to activate the connection.
  </Tab>

  <Tab title="Claude Code">
    Add the MCP server to your project's `.claude/settings.json`:

    ```json theme={}
    {
      "mcpServers": {
        "planeconnection": {
          "url": "https://mcp.planeconnection.com/mcp",
          "headers": {
            "X-API-Key": "your-api-key-here",
            "X-Workspace-ID": "your-workspace-id"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Custom MCP Client">
    Point your MCP client to the server endpoint and include the authentication
    headers on every request:

    ```
    Endpoint: https://mcp.planeconnection.com/mcp
    Headers:
      X-API-Key: your-api-key-here
      X-Workspace-ID: your-workspace-id (optional, scopes to a workspace)
    ```

    The server implements the full MCP specification including tool listing,
    tool invocation, and persistent session management.
  </Tab>
</Tabs>

## Find your workspace ID

Your workspace ID is displayed on the **Settings > General** page in
PlaneConnection. It is also visible in the URL when you are logged in:

```
https://app.planeconnection.com/{workspace-id}/ops/trips
                                 ^^^^^^^^^^^^^^
```

The `X-Workspace-ID` header is optional. If omitted, the MCP server uses the
default workspace associated with the API key. If your organization has
multiple workspaces, include the header to scope queries to the correct one.

## Verify the connection

After configuring your client, verify the connection by asking your AI agent
to list aircraft:

```
"Show me all aircraft in my fleet."
```

The agent should invoke the `list_aircraft` tool and return your fleet data. If
you receive an authentication error, verify that:

1. The API key is correct and has not been revoked.
2. The `X-Workspace-ID` header matches a workspace your key has access to.
3. The endpoint URL includes the `/mcp` path suffix.

## Server endpoint

The production MCP server endpoint is:

```
https://mcp.planeconnection.com/mcp
```

<Info>
  Contact PlaneConnection support if you need access to a non-production environment for testing
  and integration.
</Info>

## Manage API keys

### Rotate a key

<Steps>
  ### Step 1: Generate a new key

  Follow the key generation steps above to create a replacement key.

  ### Step 2: Update your AI client configuration

  Replace the old key in your client configuration with the new key.

  ### Step 3: Revoke the old key

  Return to **Settings > Integrations > API Keys** and click **Revoke** on the
  old key.
</Steps>

### Revoke a key

Navigate to **Settings > Integrations > API Keys**, find the key, and click
**Revoke**. The key is immediately invalidated. Any AI agent using that key
will receive `401 Unauthorized` responses.

## Security considerations

* **API keys grant the same access as the user who created them.** The MCP
  server inherits the creator's role and permissions for all tool invocations.
* **Never commit API keys to version control.** Use environment variables or
  secret managers.
* **Monitor usage.** The audit log under **Settings > Activity** tracks all
  MCP tool invocations with the API key name, tool invoked, and timestamp.
* **Destructive tools require confirmation.** Well-behaved MCP clients respect
  the `destructiveHint` annotation and prompt the user before invoking tools
  that create, modify, or delete data.

## Troubleshooting

<Accordion title="Connection refused or timeout">
  Verify the endpoint URL is correct and includes `/mcp`. Check that your network allows outbound
  HTTPS connections to `mcp.planeconnection.com`.
</Accordion>

<Accordion title="401 Unauthorized">
  The API key is missing, invalid, or revoked. Generate a new key from
  **Settings > Integrations > API Keys**.
</Accordion>

<Accordion title="403 Forbidden">
  The API key does not have access to the requested workspace. Check the `X-Workspace-ID` header
  value.
</Accordion>

<Accordion title="Tools not appearing in the agent">
  Restart your AI client after updating the configuration. Some clients cache the tool list and
  require a restart to pick up new tools.
</Accordion>

<Accordion title="Destructive tools blocked">
  If you created a read-only API key, destructive tools (create, update, cancel) will return an
  error. Generate a read-write key to enable full access.
</Accordion>

## Related

<CardGroup cols={2}>
  <Card title="MCP Tool Catalog" href="/reference/mcp-tools">
    Complete reference for all 88 tools across 26 domain modules.
  </Card>

  <Card title="Manage Users and Roles" href="/how-to/admin/manage-users">
    Role assignments that determine which tools an agent can invoke.
  </Card>

  <Card title="Set Up Integrations" href="/how-to/admin/set-up-integrations">
    Other integration options including QuickBooks and Stripe.
  </Card>

  <Card title="AI in Aviation Safety" href="/explanation/ai-in-aviation-safety">
    How AI tools support SMS and flight operations compliance.
  </Card>
</CardGroup>