Aspire read-only connector — build & deploy

A small remote MCP server that gives Claude/Cowork live, read-only access to your Aspire data, so you can hand management a Cowork space that answers questions straight from Aspire in real time.

How it fits together

Management (Cowork) ──▶ Claude ──▶ [Aspire read-only MCP server] ──▶ Aspire REST API
                         (custom connector, HTTPS + token)         (your ClientId/Secret)

• Aspire ClientId/Secret live only on the server — never in Claude, never shown to viewers.

• The server makes only GET requests against an allow-list of resources → read-only by construction.

• Callers must send a shared bearer token (CONNECTOR_TOKEN) to reach the server.

Related MCP server: sql-mcp

Step 1 — Create an Aspire API credential

In Aspire: System Admin → API → create a credential. Copy the ClientId and Secret. (Reference: Aspire API guide, base URL https://cloud-api.youraspire.com, Swagger at /swagger.)

Step 2 — Configure

cp .env.example .env      # then fill in ASPIRE_CLIENT_ID, ASPIRE_SECRET
# generate a long random CONNECTOR_TOKEN, e.g.:
openssl rand -hex 32

Confirm ASPIRE_TOKEN_URL against your API credential page (the POST that returns a bearer token).

Step 3 — Run locally to verify

npm install
npm run dev
# in another terminal:
curl -s localhost:8080/health          # -> {"ok":true}

Step 4 — Host it (must be public HTTPS for a claude.ai connector)

Any of these work; pick one:

• Cloudflare Workers / Render / Fly.io / Railway — deploy the repo, set the env vars as secrets.

• A small VM behind HTTPS (Caddy/nginx) running npm run build && npm start.

You need a stable URL like https://aspire-mcp.yourcompany.com/mcp.

Step 5 — Register as a custom connector in Claude

claude.ai → Settings → Connectors → Add custom connector:

• URL: https://<your-host>/mcp

• Auth: bearer token = your CONNECTOR_TOKEN

Add it at the organization level so it can be shared, not just your own account.

Auth: header, not URL

The connector token is sent in the Authorization: Bearer <token> header — nothing secret ever appears in the URL. In a Cowork plugin's .mcp.json:

{
  "mcpServers": {
    "Aspire_MCP": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer ${ASPIRE_CONNECTOR_TOKEN}" }
    }
  }
}

The server still accepts the old POST /mcp/<token> path form for backward compatibility during migration, but it is deprecated. Once every consumer sends the token as a header, delete the legacy route in index.ts and rotate CONNECTOR_TOKEN.

Step 6 — Roll out to management (read-only)

• Enable the connector for the management group/space.

• They open a Cowork space and ask questions ("show me open A/R over 60 days", "billing by division this month") — Claude answers live from Aspire.

• Because the server is GET-only over an allow-list, there is no way for a viewer to change Aspire data.

Tools exposed

• list_aspire_resources — what can be queried.

• aspire_query — generic read-only OData query (resource + $filter/$select/$top/$expand…).

• aspire_open_ar — example curated report (open invoices by customer). Add more curated tools the same way.

Extending

Add curated, named reports (like aspire_open_ar) for the questions management asks most — they're safer and faster than free-form queries, and read cleanly in Cowork.