Connector proxy
Call a connected integration's action from an app without the app ever holding the credential.
On this page
Base URL: your app's origin ($APP_ORIGIN): the published host, a custom domain, or the platform origin for the builder preview. Errors answer { ok: false, error: { code, message } } unless noted. Add x-appbricx-env: dev or prod to pick the database explicitly; otherwise the host decides (preview means dev, a published host means prod).
Authentication
- App key
- A project key or preview token identifies the app. No user session is needed.
Authorization: Bearer $APP_KEY
Endpoints
Connected integrations
GET/__appbricx/connector-proxy/available
The integrations connected for this project's owner, with their callable actions.
- Auth
- App key:
Authorization: Bearer $APP_KEY
Response
{
"integrations": [
{
"id": "slack",
"displayName": "Slack",
"actions": [
{
"name": "send_channel_message",
"displayName": "Send Message To A Channel"
}
]
}
]
}Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid Authorization bearer ("Missing Authorization: Bearer <token>", "Invalid API key"). |
curl "$APP_ORIGIN/__appbricx/connector-proxy/available" \
-H "Authorization: Bearer $APP_KEY"const res = await fetch(`${APP_ORIGIN}/__appbricx/connector-proxy/available`, {
headers: {
Authorization: `Bearer ${APP_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? data.error ?? res.statusText);Source: services/api/src/routes/connector-proxy.ts:196
Connected MCP tools
GET/__appbricx/connector-proxy/mcp/available
Tools of MCP servers connected to the workspace that the app may call.
- Auth
- App key:
Authorization: Bearer $APP_KEY
Response
{
"tools": [
{
"fullName": "mcp_linear_create_issue",
"connectorName": "Linear",
"toolName": "create_issue",
"description": "Create an issue"
}
]
}Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid Authorization bearer ("Missing Authorization: Bearer <token>", "Invalid API key"). |
curl "$APP_ORIGIN/__appbricx/connector-proxy/mcp/available" \
-H "Authorization: Bearer $APP_KEY"const res = await fetch(`${APP_ORIGIN}/__appbricx/connector-proxy/mcp/available`, {
headers: {
Authorization: `Bearer ${APP_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? data.error ?? res.statusText);Source: services/api/src/routes/connector-proxy.ts:247
Call a connected MCP tool
POST/__appbricx/connector-proxy/mcp/:toolName
Call a tool of a connected MCP server with arguments.
- Auth
- App key:
Authorization: Bearer $APP_KEY
Path parameters
| Name | Type | Description |
|---|---|---|
:toolNamerequired | string | The fullName from mcp/available (mcp_<connector>_<tool>). |
Body
| Name | Type | Description |
|---|---|---|
propsoptional | object | The tool's arguments. |
Response
A tool error: { success: false, data: null, error: { code: "MCP_TOOL_ERROR", message } }.
{
"success": true,
"data": {
"id": "ENG-42"
},
"meta": {
"connectorName": "Linear",
"toolName": "create_issue",
"durationMs": 380
}
}Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid Authorization bearer ("Missing Authorization: Bearer <token>", "Invalid API key"). |
| 403 | TOOL_NOT_ALLOWED | The key's allowed tools exclude it. |
| 429 | RATE_LIMITED | Too many requests. |
| 413 | PAYLOAD_TOO_LARGE | Over 1 MB. |
| 404 | MCP_TOOL_NOT_FOUND | No active connector offers this tool. |
curl -X POST "$APP_ORIGIN/__appbricx/connector-proxy/mcp/mcp_linear_create_issue" \
-H "Authorization: Bearer $APP_KEY" \
-H "content-type: application/json" \
-d '{"props":{"title":"Printer jam"}}'const res = await fetch(`${APP_ORIGIN}/__appbricx/connector-proxy/mcp/mcp_linear_create_issue`, {
method: "POST",
headers: {
Authorization: `Bearer ${APP_KEY}`,
"content-type": "application/json",
},
body: JSON.stringify({
"props": {
"title": "Printer jam"
}
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? data.error ?? res.statusText);Source: services/api/src/routes/connector-proxy.ts:286
Run an integration action
POST/__appbricx/connector-proxy/:integration/:action
Run one action of a connected integration server-side. The app never holds the credential; every call is audited.
- Auth
- App key:
Authorization: Bearer $APP_KEY
Path parameters
| Name | Type | Description |
|---|---|---|
:integrationrequired | string | The integration id, e.g. slack. |
:actionrequired | string | The action name (see its integration page). |
Body
| Name | Type | Description |
|---|---|---|
propsoptional | object | The action's input. |
Response
A failed action: { success: false, data: null, error: { code: "EXECUTION_FAILED", message } }.
{
"success": true,
"data": {
"ok": true,
"ts": "1697100000.000100"
},
"meta": {
"integrationId": "slack",
"actionName": "send_channel_message",
"durationMs": 412
}
}Errors
| Status | Code | When |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid Authorization bearer ("Missing Authorization: Bearer <token>", "Invalid API key"). |
| 403 | TOOL_NOT_ALLOWED | The key's allowed tools exclude this action. |
| 429 | RATE_LIMITED | Too many requests. |
| 403 | NOT_IN_ALLOWLIST | Not in .appbricx/connector-allowlist.json. |
| 403 | INTEGRATION_NOT_CONNECTED | No connection. |
| 413 | PAYLOAD_TOO_LARGE | Over 1 MB. |
| 500 | EXECUTION_ERROR | The runner threw. |
curl -X POST "$APP_ORIGIN/__appbricx/connector-proxy/slack/send_channel_message" \
-H "Authorization: Bearer $APP_KEY" \
-H "content-type: application/json" \
-d '{"props":{"channel":"C0123456","text":"Deploy finished"}}'const res = await fetch(`${APP_ORIGIN}/__appbricx/connector-proxy/slack/send_channel_message`, {
method: "POST",
headers: {
Authorization: `Bearer ${APP_KEY}`,
"content-type": "application/json",
},
body: JSON.stringify({
"props": {
"channel": "C0123456",
"text": "Deploy finished"
}
}),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? data.error ?? res.statusText);Source: services/api/src/routes/connector-proxy.ts:459