MCP server setup

Two ways to connect

An assistant reaches Aplas over MCP with one of two credentials:

Both work on the same URL. When you sign in, the client id to give your assistant is aplas-mcp; there is no secret.

Creating an API key

1. Log in to Aplas and open Config → API.
2. Click Create API Key, choose its role, and copy the generated key.

A ReadOnly key is the right default. It lets an assistant answer questions about your estate with no possibility of altering it — useful when you are trying MCP out, or connecting a client you do not fully control.

Regional endpoint

Aplas is hosted in three regions and the MCP server lives at the same regional host as the REST API, under /mcp/v1:

Use the URL that matches your organization's region. To find yours, open the Config dashboard in Aplas — the Data residency card shows your region and API endpoint. The examples below use the Australia URL; substitute your own.

Claude Code

Run the following command in your terminal:

claude mcp add --transport http aplas https://api.au.aplas.com/mcp/v1 --header "Authorization: Bearer YOUR_API_KEY"

Claude Code can also sign in, with --client-id aplas-mcp --callback-port 3118 in place of the header, but at the time of writing it still attempts dynamic client registration first and stops there (anthropics/claude-code#67258). Use an API key until that is fixed.

Cursor

1. Open Settings > MCP.
2. Click Add new MCP server.
3. Add one of the following configurations.

To sign in as yourself:

{
  "mcpServers": {
    "aplas": {
      "url": "https://api.au.aplas.com/mcp/v1",
      "auth": {
        "CLIENT_ID": "aplas-mcp"
      }
    }
  }
}

Cursor opens a browser window for the Aplas sign-in the first time it connects.

To use an API key instead:

{
  "mcpServers": {
    "aplas": {
      "url": "https://api.au.aplas.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code (GitHub Copilot)

Create or update the .vscode/mcp.json file in your project. To sign in as yourself:

{
  "servers": {
    "aplas": {
      "type": "http",
      "url": "https://api.au.aplas.com/mcp/v1",
      "oauth": {
        "clientId": "aplas-mcp"
      }
    }
  }
}

VS Code opens a browser window for the Aplas sign-in on the first connection. To use an API key instead:

{
  "servers": {
    "aplas": {
      "type": "http",
      "url": "https://api.au.aplas.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop, claude.ai and the mobile apps

These connect Aplas as a custom connector. Anthropic's infrastructure calls our server rather than your device, which works because our MCP endpoints are on the public internet.

1. Open the add-connector dialog:
   • Free, Pro and Max — Customize → Connectors → Add custom connector
   • Team and Enterprise — an owner adds it under Organization settings → Connectors → Add → Custom (choose Web if asked for a type); members then connect it from Customize → Connectors
2. Enter the MCP URL for your region, for example https://api.au.aplas.com/mcp/v1
3. Open Advanced settings and choose Use your own OAuth client — the dialog pre-selects Register automatically, which Aplas does not accept. Enter aplas-mcp as the OAuth Client ID and leave the client secret empty
4. Click Add, then Connect: Claude opens the Aplas sign-in, and after you approve the connection the connector acts as you
5. Enable Aplas from the + menu in a conversation

Each person who connects signs in as themselves, so a viewer stays read-only and an administrator can write.

Verifying the connection

Once configured, ask your assistant:

List my Aplas workspaces

A working connection returns your workspaces, each with a short id — its slug.

That request is also the first step of every session. Aplas tools are scoped to one workspace, so the assistant has to know which one you mean before it can search or write. A good client calls list_workspaces on its own and then passes the slug to everything else; if yours does not, naming the workspace in your question ("in the enterprise workspace, how many applications are Retired?") is enough.

Protocol version

The server implements MCP protocol 2025-11-25, over streamable HTTP with no session state — each call is a self-contained POST carrying its own credential. Any client supporting that revision works; the three above all do.

Troubleshooting