# MCP Server

Aerion hosts a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants read and act on your Aerion data through natural language. Once connected, your chosen client can answer questions about your Aerion records and create or update them on your behalf.

The server exposes:

- **Find, Create, Update, and Delete** tools for all core models.
- Customized **Project** and **User** analytics feeds.
- Time Entry submission and approval, and bulk approval utilities.

The server is hosted at:

```
https://cloud.aerion.app/mcp
```

Authentication uses OAuth — the first time you connect, your client opens a browser window where you sign in to your Aerion tenant.

## Permissions

The MCP server respects the same permissions as the rest of the Aerion API: it acts as the signed-in user and can only see or modify data that user has access to. We recommend connecting with a utility user scoped to the access you actually need, especially for assistants that may take destructive actions.

For production-style integrations or scripted workflows, the [REST API](/api) is still the right tool — MCP is designed for interactive use through an LLM.

## Setup

Most MCP clients accept a remote server in the same shape — a name, a URL, and (for some clients) an explicit transport type. Drop the entry below into whatever config file your client uses:

```json
{
  "mcpServers": {
    "aerion": {
      "url": "https://cloud.aerion.app/mcp"
    }
  }
}
```

Your client will handle the OAuth sign-in the first time it connects. The sections below cover where that config lives for popular clients.

### Claude

#### Claude.ai and Claude Desktop

The Connectors UI is the same on the Claude.ai web app and Claude Desktop:

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Set the name to `Aerion` and the URL to `https://cloud.aerion.app/mcp`.
4. Save, then click **Connect** and complete the sign-in flow in the browser window that opens.

> **On Enterprise plans**, custom connectors usually have to be added by a workspace admin rather than individual users. The admin also controls which tools each user is allowed to call, so once the Aerion connector is in place, make sure it's enabled — and that the specific Aerion tools you need are enabled — for your account. If you don't see **Add custom connector** in Settings, that's the missing step.

#### Claude Code

Claude Code has no Connectors UI, so the server is added from the CLI:

```bash
claude mcp add --transport http aerion https://cloud.aerion.app/mcp
```

The first time you use an Aerion tool in a session, Claude Code will open a browser window for you to sign in.

### OpenAI

#### Native Connector

The Aerion connector for ChatGPT is [available in the Apps directory](https://chatgpt.com/apps/aerion/asdk_app_6a3407353ab48191bd8f5ba551172873).

#### ChatGPT - Manual Connection in Developer Mode

If you would like to install the Aerion MCP in ChatGPT directly without the above connector, you can do so in Developer mode.

1. Open **Settings → Apps & Connectors**.
2. Scroll to **Advanced settings** at the bottom and toggle **Developer mode** on. (On Business, Enterprise, and Education plans, a workspace admin may need to allow this first.)
3. Back on **Settings → Apps & Connectors**, click **Create**.
4. Fill in the connector details:
   - **Name**: `Aerion`
   - **Description**: something like `Read and act on your Aerion data.`
   - **MCP server URL**: `https://cloud.aerion.app/mcp`
   - Leave all OAuth options at their default/self-determined values
5. Save, then complete the Aerion sign-in flow in the browser window that opens. You may need to close and re-open your ChatGPT app/window.

#### Codex CLI

Codex uses TOML rather than JSON. Add an entry to `~/.codex/config.toml`:

```toml
[mcp_servers.aerion]
url = "https://cloud.aerion.app/mcp"
```

The next time you start a Codex session, you'll be prompted to sign in.

### Cursor

Add the server to `~/.cursor/mcp.json` (create the file if it doesn't exist), using the JSON shape from the top of this section. Restart Cursor, then open **Settings → MCP** and click **Connect** next to the Aerion entry to complete the OAuth flow.

### Visual Studio Code

In your workspace, create `.vscode/mcp.json`. VS Code uses a slightly different key (`servers` instead of `mcpServers`) and requires an explicit transport type:

```json
{
  "servers": {
    "aerion": {
      "type": "http",
      "url": "https://cloud.aerion.app/mcp"
    }
  }
}
```

Then open the Command Palette and run **MCP: List Servers → Aerion → Start Server**. Sign in to Aerion in the browser window that opens.

To make the server available across all workspaces, add the same entry under `mcp.servers` in your user `settings.json` instead.