Skip to main content

​
Base URL

All API calls are made against: 
https://mcp.runalloy.com
There are two categories of endpoints:
  • Server Management API (/api/servers/...) – Create, list, update, or delete MCP servers.
  • MCP Protocol API (/mcp/...) – Called by your assistant to invoke tools and connectors via JSON‑RPC.

​
API Keys and User IDs

Management requests require two headers: 
Authorization: Bearer <API_KEY>
x-alloy-userid: <USER_ID>
  • API keys are generated in the Alloy dashboard and scoped to your account.
  • Each API key is tied to a specific user ID to support multi-tenant architectures.
  • Do not expose API keys in client-side code or public repositories.
  • Rotate keys periodically for security.

​
Token URLs vs API Authentication

MCP protocol calls support two authentication methods:

​
Token URL

Use the tokenized URL returned when creating the server: 
/mcp/{serverId}/{accessToken}
  • No additional headers required.
  • Ideal for embedding in assistants or simple client use cases.

​
API Authentication

Call the following endpoint: 
/mcp/{serverId}
Include the same headers used for management: 
Authorization: Bearer <API_KEY>
x-alloy-userid: <USER_ID>
  • Ideal for B2B scenarios where you need dynamic management of multiple users within an organization
  • Allows for token rotation and additional control
  • Enables per-user isolation without creating separate servers
  • Requires clients to sign each request

​
Optional Headers

  • x-alloy-user-token (JWT): Isolates requests by end user.
  • x-credential-id: Forces use of a specific credential.
  • x-redirect-uri: Used in OAuth flows for post-auth redirection.

​
Authentication Request Flow

This diagram shows the complete authentication and request flow:
  1. Authentication: The MCP Server validates the request authentication
  2. Rate Limiting: Checks against rate limits (100 req/min default)
  3. Restrictions: Applies any configured access restrictions
  4. API Request: Makes authenticated request to Alloy API
  5. Credential Decryption: Alloy decrypts stored platform credentials
  6. Platform Call: Executes the action on the external platform
  7. Response: Returns formatted response to MCP client

​
Best Practices

  • Least privilege: Restrict access to only the connectors and actions the server needs.
  • Rotate secrets: Periodically regenerate API keys and server tokens.
  • Isolate users: Use JWTs (x-alloy-user-token) to segregate end-user actions on shared servers.
  • Store secrets securely: Use environment variables or secret managers. Never hardcode credentials in code or HTML.
⌘I