Connecting Claude and other apps (MCP and API)

Apps can use CostCapper as you: an AI assistant such as Claude through the MCP server, or your own scripts through the API. Either way the app signs in with OAuth: you approve it once in your browser, and it can then do exactly what you can, no more. Turning your account off, or removing your admin rights, applies to your apps straight away.

Before you start (admins)

• Apps reach CostCapper over the internet or your network, so it needs an address they can reach. Set it on Settings (This appliance's address).
• Most apps refuse the appliance's own self-signed certificate. Put CostCapper behind a load balancer with an AWS Certificate Manager certificate, or give it a name and upload a certificate for that name under Settings, Address and certificate.

Claude (MCP)

Add a custom connector with the address https://your-costcapper-address/mcp. Claude opens CostCapper in your browser: sign in if asked, check the app's name and where it will be sent, and choose Allow. In Claude Code: claude mcp add --transport http costcapper https://your-costcapper-address/mcp, then /mcp to sign in.

The tools: whoami, list_machines, get_machine, turn_on (for a number of minutes), release, and for admins list_all_machines, set_managed, force_stop, lock_machine, unlock_machine and recent_activity.

The API

JSON over HTTPS at /api/v1, with Authorization: Bearer <access token>. Get a token with any OAuth 2.1 client library: discovery is at /.well-known/oauth-authorization-server, apps register themselves at /oauth/register, and sign-in uses the authorization code flow with PKCE. Access tokens last an hour; refresh tokens 30 days, and each can be used once.

• GET /api/v1/me
• GET /api/v1/machines, GET /api/v1/machines/{id}
• POST /api/v1/machines/{id}/request with {"minutes": 120} (optional), POST /api/v1/machines/{id}/release
• Admins: GET /api/v1/admin/machines, PUT /api/v1/admin/machines/{id}/managed with {"managed": true}, POST …/force-stop with {"reason": "…"}, POST …/lock with {"reason": "…", "hours": 4, "end_requests": false}, POST …/unlock, GET /api/v1/admin/audit?limit=50

Errors come back as {"error": "…"} with status 400, 403 or 404; a missing or expired token gets 401.

Disconnecting

See and disconnect your apps on Connected apps.