Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { ComposioMCPDestinationError } from '../errors/ToolRouterErrors'; |
| 2 | import type { ComposioRequestHeaders } from '../types/composio.types'; |
| 3 | import type { MCPServerType, ToolRouterMCPServerConfig } from '../types/toolRouter.types'; |
| 4 | import logger from '../utils/logger'; |
| 5 | import { ORG_ID_HEADER, PROJECT_ID_HEADER, resolveCredentialHeaders } from '../utils/sdk'; |
| 6 | |
| 7 | type OriginRole = 'API base URL' | 'MCP URL'; |
| 8 | |
| 9 | type ParsedOrigin = { origin: string } | { error: ComposioMCPDestinationError }; |
| 10 | |
| 11 | /** |
| 12 | * Returns the tuple origin (`scheme://host[:port]`) of an absolute URL. |
| 13 | * |
| 14 | * URLs without a tuple origin (`data:`, `file:`, `blob:` without a base, and |
| 15 | * similar) serialize their origin as the opaque string `null`. Two such URLs |
| 16 | * would compare equal, so they are rejected before any comparison happens. |
| 17 | */ |
| 18 | const parseOrigin = (url: string, role: OriginRole): ParsedOrigin => { |
| 19 | let parsed: URL; |
| 20 | try { |
| 21 | parsed = new URL(url); |
| 22 | } catch (_error) { |
| 23 | return { |
| 24 | error: new ComposioMCPDestinationError(`The ${role} is not a valid absolute URL`, { |
| 25 | meta: { role }, |
| 26 | }), |
| 27 | }; |
| 28 | } |
| 29 | if (parsed.origin === 'null') { |
| 30 | return { |
| 31 | error: new ComposioMCPDestinationError(`The ${role} has an opaque origin`, { |
| 32 | meta: { role }, |
| 33 | }), |
| 34 | }; |
| 35 | } |
| 36 | return { origin: parsed.origin }; |
| 37 | }; |
| 38 | |
| 39 | /** |
| 40 | * Returns the error describing why the MCP URL must not receive the session |
| 41 | * credential, or `undefined` when it shares the API origin. |
| 42 | */ |
| 43 | const destinationRejection = ( |
| 44 | apiBaseURL: string, |
| 45 | mcpUrl: string |
| 46 | ): ComposioMCPDestinationError | undefined => { |
| 47 | const api = parseOrigin(apiBaseURL, 'API base URL'); |
| 48 | if ('error' in api) { |
| 49 | return api.error; |
| 50 | } |
| 51 | const mcp = parseOrigin(mcpUrl, 'MCP URL'); |
| 52 | if ('error' in mcp) { |
| 53 | return mcp.error; |
| 54 | } |
| 55 | if (mcp.origin === api.origin) { |
| 56 | return undefined; |
| 57 | } |
| 58 | return new ComposioMCPDestinationError( |
| 59 | `The session MCP endpoint origin ${mcp.origin} does not match the API origin ${api.origin}; the session credential was not attached`, |
| 60 | { meta: { mcpOrigin: mcp.origin, apiOrigin: api.origin } } |
| 61 | ); |
| 62 | }; |
| 63 | |
| 64 | export type MCPServerConfigInput = { |
| 65 | type: MCPServerType; |
| 66 | /** The MCP URL returned by the API for this session. */ |
| 67 | url: string; |
| 68 | /** The API base URL the session request was sent to. */ |
| 69 | apiBaseURL: string; |
| 70 | /** The project API key the session request authenticated with, or `null` when disabled. */ |
| 71 | apiKey: string | null | undefined; |
| 72 | /** The user API key the client resolved (`userApiKey` option or `COMPOSIO_USER_API_KEY`). */ |
| 73 | userApiKey: string | null | undefined; |
| 74 | /** The organization API key the client resolved (`orgApiKey` option or `COMPOSIO_ORG_API_KEY`). */ |
| 75 | orgApiKey?: string | null; |
| 76 | /** The default headers configured on the SDK instance; only `x-user-api-key` is consulted. */ |
| 77 | defaultHeaders: ComposioRequestHeaders | undefined; |
| 78 | /** Organization nano ID the instance is scoped to, if any. */ |
| 79 | orgId: string | undefined; |
| 80 | /** Project nano ID the instance is scoped to, if any. */ |
| 81 | projectId: string | undefined; |
| 82 | /** |
| 83 | * Whether the caller asked for the MCP endpoint (`mcp: true`). Decides how |
| 84 | * a rejected destination is reported: as a thrown error when `true`, as a |
| 85 | * warning and an empty header set otherwise. |
| 86 | */ |
| 87 | mcpRequested: boolean; |
| 88 | }; |
| 89 | |
| 90 | /** |
| 91 | * Builds the MCP server config exported on a session. |
| 92 | * |
| 93 | * The headers mirror the effective auth context of the session request: the |
| 94 | * project key as `x-api-key` when one is configured, otherwise the resolved |
| 95 | * user API key (the `userApiKey` option, then the `x-user-api-key` default |
| 96 | * header) as `x-user-api-key`, plus `x-org-id` / `x-project-id` when the |
| 97 | * instance carries an explicit scope. No other default header is copied and |
| 98 | * the environment is never re-read. |
| 99 | * |
| 100 | * The headers are only attached when the MCP URL has the same origin as the |
| 101 | * API base URL the session was created against, whatever scheme the caller |
| 102 | * configured: that origin already receives them on every SDK request. Any |
| 103 | * other destination (a different origin, an opaque origin, or a URL that does |
| 104 | * not parse) never receives the credential. When the caller asked for MCP |
| 105 | * (`mcpRequested`), that raises {@link ComposioMCPDestinationError} naming |
| 106 | * both origins; otherwise the session is returned with empty `headers` and a |
| 107 | * warning naming both origins is logged, so callers who only use the native |
| 108 | * tools are not blocked by an endpoint they never consume. The SDK itself |
| 109 | * never connects to the MCP URL and does not follow redirects for it; an MCP |
| 110 | * client consuming this config must not forward these headers to a different |
| 111 | * origin. |
| 112 | */ |
| 113 | export const buildMCPServerConfig = (input: MCPServerConfigInput): ToolRouterMCPServerConfig => { |
| 114 | const rejection = destinationRejection(input.apiBaseURL, input.url); |
| 115 | if (rejection) { |
| 116 | if (input.mcpRequested) { |
| 117 | throw rejection; |
| 118 | } |
| 119 | logger.warn( |
| 120 | `${rejection.message}. session.mcp.headers was left empty; pass \`mcp: true\` to make this an error` |
| 121 | ); |
| 122 | return { type: input.type, url: input.url, headers: {} }; |
| 123 | } |
| 124 | |
| 125 | const headers = resolveCredentialHeaders(input); |
| 126 | if (input.orgId) { |
| 127 | headers[ORG_ID_HEADER] = input.orgId; |
| 128 | } |
| 129 | if (input.projectId) { |
| 130 | headers[PROJECT_ID_HEADER] = input.projectId; |
| 131 | } |
| 132 | |
| 133 | return { type: input.type, url: input.url, headers }; |
| 134 | }; |