View as Markdown

MCP server

The Aleta MCP server lets AI apps that speak the Model Context Protocol (Claude, ChatGPT, Cursor, Codex and others) work with your Aleta data. You connect an app once, pick one workspace and choose whether it may only read or also make changes. You manage and revoke connections in Settings, Connections.

The server is hosted by Aleta and follows the authorization part of the MCP specification: Streamable HTTP transport, OAuth 2.1 sign-in in your browser and dynamic client registration. You never copy a key or token by hand.

Server URL

MCP server URL
https://mcp.aleta.ai/mcp

If your firm uses Aleta under its own domain, Settings, Connections shows the server URL to use, for example https://mcp.yourfirm.com/mcp. Copy the URL from there: it always names the server that works for your firm.

How connecting works

  1. Add the server URL to your app (see the clients below).
  2. The app opens Aleta in your browser. Sign in as you normally do.
  3. Pick the workspace the app may use. A connection always covers exactly one workspace. If you work in several firms, connect once per workspace.
  4. Pick the access:
    • Read only (the default): the app can read portfolios, holdings, transactions, reports and the rest of your data, and cannot change anything.
    • Read and write: the app can also create and change data through the Aleta API. It is only offered when your role in that workspace can write; viewers always connect read only.
  5. Confirm. The browser hands control back to your app, which is now connected.

The authorization request is valid for 10 minutes and can be used once. If you see "This authorization has expired", go back to your app and connect again.

Claude

Claude Desktop and claude.ai

Open Settings, Connectors, choose Add custom connector and paste https://mcp.aleta.ai/mcp. Claude opens the Aleta sign-in the first time you connect.

Claude Code

Shell
claude mcp add --transport http aleta https://mcp.aleta.ai/mcp

Then run /mcp inside a Claude Code session and pick aleta to sign in.

ChatGPT

Open Settings, Apps and Connectors. Under Advanced settings, turn on Developer mode, then create a connector with the URL https://mcp.aleta.ai/mcp and OAuth authentication. ChatGPT opens the Aleta sign-in when you connect.

Cursor

Open Cursor Settings, go to MCP and choose Add new MCP server, or add this entry to your mcp.json:

JSON
{
  "mcpServers": {
    "aleta": {
      "url": "https://mcp.aleta.ai/mcp"
    }
  }
}

Cursor then asks you to log in to the server, which opens the Aleta sign-in.

Codex

The Codex CLI and the IDE extension share configuration.

Shell
codex mcp add aleta --url https://mcp.aleta.ai/mcp
codex mcp login aleta

The login command opens the Aleta sign-in in your browser.

Other clients

Any client with remote MCP support (Streamable HTTP and OAuth) can connect: add a remote server with the URL https://mcp.aleta.ai/mcp. A client that only runs local (stdio) servers can use the mcp-remote bridge:

Command

npx

Arguments

-y mcp-remote https://mcp.aleta.ai/mcp

What Aleta exposes

The server reaches every route of the Aleta API: v1 and the legacy v2 and v3 routes. Each call carries the token of your connection, and the API checks it exactly as a direct call from you, limited to the workspace and the access you chose. The app can never do more than you can.

find_api_operations

Finds operations by version, read or write, and words in the method and path. Each result has the operation id (METHOD /path/{param}), its path parameters, the scopes it accepts and whether it takes dry_run, Idempotency-Key and as_of.

call_api_read

Calls a read operation with path parameters and query parameters (filters, cursor, limit, as_of, expand). Returns the API's JSON unchanged.

call_api_write

Calls a write operation with a JSON body. On v1, dry_run: true checks and plans the write without storing anything, and idempotency_key makes a retry safe. v2 and v3 have neither, so the server refuses both there. Returns { status, dry_run, idempotency_replay, body }. Only available on a Read and write connection.

Errors keep the API's problem details, including next_action on a 409. Two routes are limited: a data deletion request is always a dry run through MCP, because only a person may send it, and closing a tenant (DELETE /v1/tenants/{tenant_id}) is not reachable. Retired routes are not reachable either.

Revoking access

Open Settings, Connections in Aleta. Under AI apps you see every connection with its workspace, access, when it was connected and when it was last used. Choose Revoke and confirm.

Revoking takes effect on the app's next call: that call is refused, and the app asks you to connect again.

FAQ

Read and write is greyed out

Your role in that workspace is read only (for example Viewer), so the connection can only read. Ask your firm's administrator if you need to make changes.

The sign-in shows no workspaces

The account you signed in with has no access to an Aleta workspace, or not to your firm's workspace on its own domain. Sign in with the account your firm invited.

I want the app in another workspace

Connect the app again and pick the other workspace. Each connection covers one workspace.

Numbers don't match the dashboard

The server sees what your own account sees in the chosen workspace. If the app sees fewer portfolios than you expect, check that it is connected to the right workspace.

The client reports 'unauthorized' after working previously

The connection was revoked or its sign-in expired. Connect again from the app (re-add the connector or run its sign-in command).

Can I authenticate with an API key instead of OAuth?

Yes. Exchange your API key for an access token (aleta_at_..., see credentials) and send it as Authorization: Bearer <token>. The server passes it to the Aleta API, which applies the key's rights. Write tools need a key with at least one write scope and the platform:read scope, which the server uses to read the key's scopes.

Building your own client

Any client that speaks MCP over Streamable HTTP and supports OAuth can connect; we don't gate on specific apps. The server publishes its OAuth metadata at https://mcp.aleta.ai/.well-known/oauth-protected-resource. For protocol details, see the MCP specification. For the data shape the server returns, see the Aleta API reference.