MCP Ambassador exposes two REST APIs: the Admin API for system management and the User API for client operations.
Base URLs
| API | Base URL | Authentication |
|---|
| Admin API | https://your-host:9443/v1/admin | Admin session cookie or X-Admin-Key header |
| Client API | https://your-host:8443/v1 | X-Session-Token: amb_st_... |
Authentication
Admin API
Admin endpoints require either:
- Session cookie — obtained by logging in via
POST /v1/admin/login - Admin API key —
X-Admin-Key: adminkey_XXXXXXXXXXXXXXXX (less preferred)
# Login and get session cookie
curl -k -c cookies.txt \
-X POST https://localhost:9443/v1/admin/login \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "admin123"}'
# Use session cookie for subsequent requests
curl -k -b cookies.txt https://localhost:9443/v1/admin/users
Client API (Ambassador Client)
Client endpoints use ephemeral session tokens:
# Register (first time, with preshared key)
curl -k -X POST https://localhost:8443/v1/clients/register \
-H "Content-Type: application/json" \
-d '{
"friendly_name": "VS Code - Dev Laptop",
"host_tool": "vscode",
"preshared_key": "amb_pk_your_key_here"
}'
# → {"session_token": "amb_st_...", "user_id": "...", "ca_fingerprint": "..."}
# Fetch tool catalog
curl -k https://localhost:8443/v1/tools \
-H "X-Session-Token: amb_st_your_token"
# Invoke a tool
curl -k -X POST https://localhost:8443/v1/tools/call \
-H "X-Session-Token: amb_st_your_token" \
-H "Content-Type: application/json" \
-d '{"tool": "github.search_code", "arguments": {"query": "authentication"}}'
Admin API — Key Endpoints
Users
| Method | Path | Description |
|---|
GET | /v1/admin/users | List all users |
POST | /v1/admin/users | Create a user |
GET | /v1/admin/users/:id | Get user details |
PUT | /v1/admin/users/:id | Update user |
DELETE | /v1/admin/users/:id | Deactivate user |
POST | /v1/admin/users/:id/reset-password | Reset user password |
Groups
| Method | Path | Description |
|---|
GET | /v1/admin/groups | List all groups |
POST | /v1/admin/groups | Create a group |
PUT | /v1/admin/groups/:id/members | Add/remove members |
PUT | /v1/admin/groups/:id/mcps | Assign MCPs to group |
MCP Catalog
| Method | Path | Description |
|---|
GET | /v1/admin/mcps | List all MCPs in catalog |
POST | /v1/admin/mcps | Add MCP to catalog |
POST | /v1/admin/mcps/:id/validate | Validate MCP connectivity |
POST | /v1/admin/mcps/:id/publish | Publish MCP to marketplace |
POST | /v1/admin/mcps/:id/archive | Archive MCP |
PUT | /v1/admin/mcps/:id/tools/:tool/kill | Kill switch a specific tool |
PUT | /v1/admin/mcps/:id/kill | Kill switch entire MCP |
Audit Logs
| Method | Path | Description |
|---|
GET | /v1/admin/audit | Query audit log (paginated) |
GET | /v1/admin/audit?type=tool_invocation | Filter by event type |
GET | /v1/admin/audit?user=alice | Filter by user |
User API — Key Endpoints
Clients
| Method | Path | Description |
|---|
POST | /v1/clients/register | Register a new client |
GET | /v1/clients | List user's clients |
DELETE | /v1/clients/:id | Deactivate a client |
POST | /v1/session/heartbeat | Keep session alive |
| Method | Path | Description |
|---|
GET | /v1/tools | Get personalized tool catalog |
POST | /v1/tools/call | Invoke a tool |
Subscriptions
| Method | Path | Description |
|---|
GET | /v1/marketplace | Browse available MCPs |
POST | /v1/subscriptions | Subscribe to an MCP |
GET | /v1/subscriptions | List active subscriptions |
PUT | /v1/subscriptions/:id | Update tools/credentials |
DELETE | /v1/subscriptions/:id | Unsubscribe |
Health check
curl -k https://localhost:8443/health
# → {"status":"ok","version":"0.8.0-beta.1"}
curl -k https://localhost:9443/health
# → {"status":"ok","version":"0.8.0-beta.1","admin":true}
Full API reference
For complete request/response schemas and error codes, see the Admin API Reference and User API Reference.