Connections (MCP servers)

External tool servers (Model Context Protocol) that the agent may call on the user's behalf — GitHub, Linear, an internal API — connected from the Connections page with the user's own login (OAuth) or an API key.

Endpoints

Method	Path	Purpose
GET	`/mcp-servers/servers/`	My connected servers
POST	`/mcp-servers/servers/`	Connect a server
GET	`/mcp-servers/servers/{id}/`	Get a server
PUT	`/mcp-servers/servers/{id}/`	Update a server
DELETE	`/mcp-servers/servers/{id}/`	Disconnect a server
POST	`/mcp-servers/servers/{id}/test/`	Test a saved server
POST	`/mcp-servers/servers/test/`	Test an unsaved configuration
POST	`/mcp-servers/servers/discover/`	Does this server support sign-in?
POST	`/mcp-servers/servers/{id}/oauth/start/`	Start sign-in for an OAuth server
POST	`/mcp-servers/oauth/callback/`	Finish sign-in

GET `/mcp-servers/servers/`

My connected servers

Auth: Session token · In the app: Connections page

Response 200 — Servers, newest first.

Array of:

Field	Type	Description
`id`	integer
`label`	string	Display name.
`slug`	string	Short key the agent uses to name the server's tools.
`url`	string	The server's MCP endpoint (HTTPS).
`auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)
`auth_header_name`	string	For `header` auth (e.g. `X-API-Key`).
`secret`	string	Write-only token / API key for `bearer` and `header` auth.
`has_secret`	boolean
`enabled`	boolean	Disabled servers are kept but not offered to the agent.
`status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)
`last_ok_at`	string (date-time), nullable
`last_error`	string
`tool_count`	integer	Tools discovered on the last successful test.
`tool_names`	string[]
`granted_scopes`	string	OAuth scopes granted (space-separated).
`token_expires_at`	string (date-time), nullable
`oauth_provider`	string, nullable	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`created_at`	string (date-time)
`updated_at`	string (date-time)
`user`	integer

Example

bash

curl -X GET "https://api.example.com/mcp-servers/servers/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST `/mcp-servers/servers/`

Connect a server

Saves the connection (max 10 per user). For oauth servers, follow with oauth/start/; for token-based ones, test it with {id}/test/.

Auth: Session token · In the app: Connections → Add

Request body (application/json)

Field	Type	Required	Description
`id`	integer	no
`label`	string	no	Display name.
`slug`	string	no	Short key the agent uses to name the server's tools.
`url`	string	no	The server's MCP endpoint (HTTPS).
`auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)	no
`auth_header_name`	string	no	For `header` auth (e.g. `X-API-Key`).
`secret`	string	no	Write-only token / API key for `bearer` and `header` auth.
`has_secret`	boolean	no
`enabled`	boolean	no	Disabled servers are kept but not offered to the agent.
`status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)	no
`last_ok_at`	string (date-time), nullable	no
`last_error`	string	no
`tool_count`	integer	no	Tools discovered on the last successful test.
`tool_names`	string[]	no
`granted_scopes`	string	no	OAuth scopes granted (space-separated).
`token_expires_at`	string (date-time), nullable	no
`oauth_provider`	string, nullable	no	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`created_at`	string (date-time)	no
`updated_at`	string (date-time)	no
`user`	integer	no

json

{
  "label": "Internal tools",
  "slug": "tools",
  "url": "https://mcp.acme.internal/mcp",
  "auth_type": "header",
  "auth_header_name": "X-API-Key",
  "secret": "s3cret"
}

Response 201 — Saved.

Field	Type	Description
`id`	integer
`label`	string	Display name.
`slug`	string	Short key the agent uses to name the server's tools.
`url`	string	The server's MCP endpoint (HTTPS).
`auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)
`auth_header_name`	string	For `header` auth (e.g. `X-API-Key`).
`secret`	string	Write-only token / API key for `bearer` and `header` auth.
`has_secret`	boolean
`enabled`	boolean	Disabled servers are kept but not offered to the agent.
`status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)
`last_ok_at`	string (date-time), nullable
`last_error`	string
`tool_count`	integer	Tools discovered on the last successful test.
`tool_names`	string[]
`granted_scopes`	string	OAuth scopes granted (space-separated).
`token_expires_at`	string (date-time), nullable
`oauth_provider`	string, nullable	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`created_at`	string (date-time)
`updated_at`	string (date-time)
`user`	integer

json

{
  "id": 5,
  "label": "GitHub",
  "slug": "github",
  "url": "https://api.githubcopilot.com/mcp/",
  "auth_type": "oauth",
  "auth_header_name": "",
  "has_secret": true,
  "enabled": true,
  "status": "ok",
  "last_ok_at": "2026-09-22T06:00:00Z",
  "last_error": "",
  "tool_count": 42,
  "tool_names": [
    "list_issues",
    "create_issue",
    "search_code"
  ],
  "granted_scopes": "repo read:user",
  "token_expires_at": "2026-09-22T14:00:00Z",
  "oauth_provider": "github.com",
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-22T06:00:00Z",
  "user": 42
}

Response 400 — Validation error or server limit reached.

json

{
  "detail": "You can connect at most 10 servers."
}

Example

bash

curl -X POST "https://api.example.com/mcp-servers/servers/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Internal tools","slug":"tools","url":"https://mcp.acme.internal/mcp","auth_type":"header","auth_header_name":"X-API-Key","secret":"s3cret"}'

GET `/mcp-servers/servers/{id}/`

Get a server

Auth: Session token

Path parameters

Field	Type	Required	Description
`id`	integer	yes

Response 200 — The server.

Field	Type	Description
`id`	integer
`label`	string	Display name.
`slug`	string	Short key the agent uses to name the server's tools.
`url`	string	The server's MCP endpoint (HTTPS).
`auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)
`auth_header_name`	string	For `header` auth (e.g. `X-API-Key`).
`secret`	string	Write-only token / API key for `bearer` and `header` auth.
`has_secret`	boolean
`enabled`	boolean	Disabled servers are kept but not offered to the agent.
`status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)
`last_ok_at`	string (date-time), nullable
`last_error`	string
`tool_count`	integer	Tools discovered on the last successful test.
`tool_names`	string[]
`granted_scopes`	string	OAuth scopes granted (space-separated).
`token_expires_at`	string (date-time), nullable
`oauth_provider`	string, nullable	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`created_at`	string (date-time)
`updated_at`	string (date-time)
`user`	integer

json

{
  "id": 5,
  "label": "GitHub",
  "slug": "github",
  "url": "https://api.githubcopilot.com/mcp/",
  "auth_type": "oauth",
  "auth_header_name": "",
  "has_secret": true,
  "enabled": true,
  "status": "ok",
  "last_ok_at": "2026-09-22T06:00:00Z",
  "last_error": "",
  "tool_count": 42,
  "tool_names": [
    "list_issues",
    "create_issue",
    "search_code"
  ],
  "granted_scopes": "repo read:user",
  "token_expires_at": "2026-09-22T14:00:00Z",
  "oauth_provider": "github.com",
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-22T06:00:00Z",
  "user": 42
}

Response 404 — Not yours.

Example

bash

curl -X GET "https://api.example.com/mcp-servers/servers/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT `/mcp-servers/servers/{id}/`

Update a server

Partial update. Changing url, auth_type, auth_header_name or secret resets status (to needs_reauth for OAuth servers).

Auth: Session token

Path parameters

Field	Type	Required	Description
`id`	integer	yes

Request body (application/json)

Field	Type	Required	Description
`id`	integer	no
`label`	string	no	Display name.
`slug`	string	no	Short key the agent uses to name the server's tools.
`url`	string	no	The server's MCP endpoint (HTTPS).
`auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)	no
`auth_header_name`	string	no	For `header` auth (e.g. `X-API-Key`).
`secret`	string	no	Write-only token / API key for `bearer` and `header` auth.
`has_secret`	boolean	no
`enabled`	boolean	no	Disabled servers are kept but not offered to the agent.
`status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)	no
`last_ok_at`	string (date-time), nullable	no
`last_error`	string	no
`tool_count`	integer	no	Tools discovered on the last successful test.
`tool_names`	string[]	no
`granted_scopes`	string	no	OAuth scopes granted (space-separated).
`token_expires_at`	string (date-time), nullable	no
`oauth_provider`	string, nullable	no	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`created_at`	string (date-time)	no
`updated_at`	string (date-time)	no
`user`	integer	no

json

{
  "enabled": false
}

Response 200 — Updated.

Field	Type	Description
`id`	integer
`label`	string	Display name.
`slug`	string	Short key the agent uses to name the server's tools.
`url`	string	The server's MCP endpoint (HTTPS).
`auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)
`auth_header_name`	string	For `header` auth (e.g. `X-API-Key`).
`secret`	string	Write-only token / API key for `bearer` and `header` auth.
`has_secret`	boolean
`enabled`	boolean	Disabled servers are kept but not offered to the agent.
`status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)
`last_ok_at`	string (date-time), nullable
`last_error`	string
`tool_count`	integer	Tools discovered on the last successful test.
`tool_names`	string[]
`granted_scopes`	string	OAuth scopes granted (space-separated).
`token_expires_at`	string (date-time), nullable
`oauth_provider`	string, nullable	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`created_at`	string (date-time)
`updated_at`	string (date-time)
`user`	integer

json

{
  "id": 5,
  "label": "GitHub",
  "slug": "github",
  "url": "https://api.githubcopilot.com/mcp/",
  "auth_type": "oauth",
  "auth_header_name": "",
  "has_secret": true,
  "enabled": true,
  "status": "ok",
  "last_ok_at": "2026-09-22T06:00:00Z",
  "last_error": "",
  "tool_count": 42,
  "tool_names": [
    "list_issues",
    "create_issue",
    "search_code"
  ],
  "granted_scopes": "repo read:user",
  "token_expires_at": "2026-09-22T14:00:00Z",
  "oauth_provider": "github.com",
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-22T06:00:00Z",
  "user": 42
}

Example

bash

curl -X PUT "https://api.example.com/mcp-servers/servers/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

DELETE `/mcp-servers/servers/{id}/`

Disconnect a server

Revokes OAuth tokens with the provider where possible, then deletes the row.

Auth: Session token

Path parameters

Field	Type	Required	Description
`id`	integer	yes

Response 200 — Deleted.

Field	Type	Description
`message`	string

json

{
  "message": "OK"
}

Example

bash

curl -X DELETE "https://api.example.com/mcp-servers/servers/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST `/mcp-servers/servers/{id}/test/`

Test a saved server

Connects, lists tools and records the outcome on the server (status, tool_count, tool_names).

Auth: Session token · In the app: Connections → Test

Path parameters

Field	Type	Required	Description
`id`	integer	yes

Response 200 — Probe result.

Field	Type	Description
`ok`	boolean
`error`	string
`needs_reauth`	boolean
`tool_count`	integer
`tool_names`	string[]
`latency_ms`	integer
`server`	object	An external MCP (Model Context Protocol) tool server connected by the user. Credentials are write-only and never returned.
`server.id`	integer
`server.label`	string	Display name.
`server.slug`	string	Short key the agent uses to name the server's tools.
`server.url`	string	The server's MCP endpoint (HTTPS).
`server.auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)
`server.auth_header_name`	string	For `header` auth (e.g. `X-API-Key`).
`server.secret`	string	Write-only token / API key for `bearer` and `header` auth.
`server.has_secret`	boolean
`server.enabled`	boolean	Disabled servers are kept but not offered to the agent.
`server.status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)
`server.last_ok_at`	string (date-time), nullable
`server.last_error`	string
`server.tool_count`	integer	Tools discovered on the last successful test.
`server.tool_names`	string[]
`server.granted_scopes`	string	OAuth scopes granted (space-separated).
`server.token_expires_at`	string (date-time), nullable
`server.oauth_provider`	string, nullable	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`server.created_at`	string (date-time)
`server.updated_at`	string (date-time)
`server.user`	integer

json

{
  "ok": true,
  "error": "",
  "tool_count": 42,
  "tool_names": [
    "list_issues",
    "create_issue"
  ],
  "latency_ms": 310
}

Example

bash

curl -X POST "https://api.example.com/mcp-servers/servers/<id>/test/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST `/mcp-servers/servers/test/`

Test an unsaved configuration

Same probe, for the "Add" form before saving. Send the fields of a server; include id to reuse a saved server's stored secret.

Auth: Session token · In the app: Connections → Add → Test

Request body (application/json)

Field	Type	Required	Description
`id`	integer	no
`label`	string	no	Display name.
`slug`	string	no	Short key the agent uses to name the server's tools.
`url`	string	no	The server's MCP endpoint (HTTPS).
`auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)	no
`auth_header_name`	string	no	For `header` auth (e.g. `X-API-Key`).
`secret`	string	no	Write-only token / API key for `bearer` and `header` auth.
`has_secret`	boolean	no
`enabled`	boolean	no	Disabled servers are kept but not offered to the agent.
`status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)	no
`last_ok_at`	string (date-time), nullable	no
`last_error`	string	no
`tool_count`	integer	no	Tools discovered on the last successful test.
`tool_names`	string[]	no
`granted_scopes`	string	no	OAuth scopes granted (space-separated).
`token_expires_at`	string (date-time), nullable	no
`oauth_provider`	string, nullable	no	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`created_at`	string (date-time)	no
`updated_at`	string (date-time)	no
`user`	integer	no

json

{
  "id": 5,
  "label": "GitHub",
  "slug": "github",
  "url": "https://api.githubcopilot.com/mcp/",
  "auth_type": "oauth",
  "auth_header_name": "",
  "has_secret": true,
  "enabled": true,
  "status": "ok",
  "last_ok_at": "2026-09-22T06:00:00Z",
  "last_error": "",
  "tool_count": 42,
  "tool_names": [
    "list_issues",
    "create_issue",
    "search_code"
  ],
  "granted_scopes": "repo read:user",
  "token_expires_at": "2026-09-22T14:00:00Z",
  "oauth_provider": "github.com",
  "created_at": "2026-09-01T09:00:00Z",
  "updated_at": "2026-09-22T06:00:00Z",
  "user": 42
}

Response 200 — Probe result.

Field	Type	Description
`ok`	boolean
`error`	string
`needs_reauth`	boolean
`tool_count`	integer
`tool_names`	string[]
`latency_ms`	integer
`server`	object	An external MCP (Model Context Protocol) tool server connected by the user. Credentials are write-only and never returned.
`server.id`	integer
`server.label`	string	Display name.
`server.slug`	string	Short key the agent uses to name the server's tools.
`server.url`	string	The server's MCP endpoint (HTTPS).
`server.auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)
`server.auth_header_name`	string	For `header` auth (e.g. `X-API-Key`).
`server.secret`	string	Write-only token / API key for `bearer` and `header` auth.
`server.has_secret`	boolean
`server.enabled`	boolean	Disabled servers are kept but not offered to the agent.
`server.status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)
`server.last_ok_at`	string (date-time), nullable
`server.last_error`	string
`server.tool_count`	integer	Tools discovered on the last successful test.
`server.tool_names`	string[]
`server.granted_scopes`	string	OAuth scopes granted (space-separated).
`server.token_expires_at`	string (date-time), nullable
`server.oauth_provider`	string, nullable	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`server.created_at`	string (date-time)
`server.updated_at`	string (date-time)
`server.user`	integer

json

{
  "ok": true,
  "error": "",
  "tool_count": 42,
  "tool_names": [
    "list_issues",
    "create_issue"
  ],
  "latency_ms": 310
}

Example

bash

curl -X POST "https://api.example.com/mcp-servers/servers/test/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":5,"label":"GitHub","slug":"github","url":"https://api.githubcopilot.com/mcp/","auth_type":"oauth","auth_header_name":"","has_secret":true,"enabled":true,"status":"ok","last_ok_at":"2026-09-22T06:00:00Z","last_error":"","tool_count":42,"tool_names":["list_issues","create_issue","search_code"],"granted_scopes":"repo read:user","token_expires_at":"2026-09-22T14:00:00Z","oauth_provider":"github.com","created_at":"2026-09-01T09:00:00Z","updated_at":"2026-09-22T06:00:00Z","user":42}'

POST `/mcp-servers/servers/discover/`

Does this server support sign-in?

Inspects the server's OAuth metadata. available: true means you can connect with auth_type: oauth; needs_admin means the provider requires a pre-registered client an administrator must configure.

Auth: Session token · In the app: Connections → Add (as you type the URL)

Request body (application/json)

Field	Type	Required	Description
`url`	string	yes

json

{
  "url": "https://mcp.notion.com/mcp"
}

Response 200 — Discovery result.

Field	Type	Description
`oauth`	object
`oauth.available`	boolean
`oauth.provider`	string, nullable
`oauth.scopes`	string[]
`oauth.default_scopes`	string[]
`oauth.dynamic_registration`	boolean
`oauth.needs_admin`	boolean
`oauth.error`	string, nullable

json

{
  "oauth": {
    "available": true,
    "provider": "mcp.notion.com",
    "scopes": [],
    "default_scopes": [],
    "dynamic_registration": true,
    "needs_admin": false,
    "error": null
  }
}

Example

bash

curl -X POST "https://api.example.com/mcp-servers/servers/discover/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mcp.notion.com/mcp"}'

POST `/mcp-servers/servers/{id}/oauth/start/`

Start sign-in for an OAuth server

Returns the provider's authorisation URL to open in a browser. After consent the provider redirects to the app's callback page, which posts code and state to oauth/callback/.

Auth: Session token · In the app: Connections → Sign in

Path parameters

Field	Type	Required	Description
`id`	integer	yes

Request body (application/json, optional)

Field	Type	Required	Description
`scopes`	string[]	no	Subset of the discovered scopes to request.

Response 200 — Redirect the user to auth_url.

Field	Type	Description
`auth_url`	string (uri)
`state`	string
`scopes`	string[]
`provider`	string

Response 400 — The server does not support sign-in, or the provider refused.

json

{
  "detail": "Authentication credentials were not provided."
}

Example

bash

curl -X POST "https://api.example.com/mcp-servers/servers/<id>/oauth/start/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST `/mcp-servers/oauth/callback/`

Finish sign-in

Exchanges the code for tokens, stores them on the server and runs a test. Each state can be used once.

Auth: Session token · In the app: /connections-callback page

Request body (application/json)

Field	Type	Required	Description
`code`	string	yes
`state`	string	yes

Response 200 — Signed in; probe result with the updated server.

Field	Type	Description
`ok`	boolean
`error`	string
`needs_reauth`	boolean
`tool_count`	integer
`tool_names`	string[]
`latency_ms`	integer
`server`	object	An external MCP (Model Context Protocol) tool server connected by the user. Credentials are write-only and never returned.
`server.id`	integer
`server.label`	string	Display name.
`server.slug`	string	Short key the agent uses to name the server's tools.
`server.url`	string	The server's MCP endpoint (HTTPS).
`server.auth_type`	string (`"none"`, `"bearer"`, `"header"`, `"oauth"`)
`server.auth_header_name`	string	For `header` auth (e.g. `X-API-Key`).
`server.secret`	string	Write-only token / API key for `bearer` and `header` auth.
`server.has_secret`	boolean
`server.enabled`	boolean	Disabled servers are kept but not offered to the agent.
`server.status`	string (`"untested"`, `"ok"`, `"error"`, `"needs_reauth"`)
`server.last_ok_at`	string (date-time), nullable
`server.last_error`	string
`server.tool_count`	integer	Tools discovered on the last successful test.
`server.tool_names`	string[]
`server.granted_scopes`	string	OAuth scopes granted (space-separated).
`server.token_expires_at`	string (date-time), nullable
`server.oauth_provider`	string, nullable	Host of the OAuth issuer, e.g. `mcp.notion.com`.
`server.created_at`	string (date-time)
`server.updated_at`	string (date-time)
`server.user`	integer

json

{
  "ok": true,
  "error": "",
  "tool_count": 42,
  "tool_names": [
    "list_issues",
    "create_issue"
  ],
  "latency_ms": 310
}

Response 400 — Invalid, expired or already-used state; or the provider rejected the code (server is included so the UI can show its state).

json

{
  "detail": "Authentication credentials were not provided."
}

Example

bash

curl -X POST "https://api.example.com/mcp-servers/oauth/callback/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

Connections (MCP servers) ​

Endpoints ​

GET /mcp-servers/servers/ ​

POST /mcp-servers/servers/ ​

GET /mcp-servers/servers/{id}/ ​

PUT /mcp-servers/servers/{id}/ ​

DELETE /mcp-servers/servers/{id}/ ​

POST /mcp-servers/servers/{id}/test/ ​

POST /mcp-servers/servers/test/ ​

POST /mcp-servers/servers/discover/ ​

POST /mcp-servers/servers/{id}/oauth/start/ ​

POST /mcp-servers/oauth/callback/ ​

Connections (MCP servers)

Endpoints

GET `/mcp-servers/servers/`

POST `/mcp-servers/servers/`

GET `/mcp-servers/servers/{id}/`

PUT `/mcp-servers/servers/{id}/`

DELETE `/mcp-servers/servers/{id}/`

POST `/mcp-servers/servers/{id}/test/`

POST `/mcp-servers/servers/test/`

POST `/mcp-servers/servers/discover/`

POST `/mcp-servers/servers/{id}/oauth/start/`

POST `/mcp-servers/oauth/callback/`