Integrations

Give the agent HTTP endpoints and MCP servers as tools, with a bearer token from the vault when they need one.

What an integration is

A connection the project's administrators define, test, and then allow runs to select. Three kinds:

• Connected service (OAuth). A catalogued provider — GitHub first — connected through its own consent page: Connect on the GitHub row in the console opens it in a small window (or POST /v1/integrations/oauth/github and send the browser to the returned authorization_url). The platform keeps the token, refreshes it, and runs the provider's tools itself: github_whoami, github_list_repos, github_get_file, github_list_issues, github_get_issue, github_create_issue, github_comment_issue. The agent sees tool names and small results, never the token. Disconnect tells the provider to forget the token. A deployment offers a provider only when its operator registered an OAuth app for it (STEALTH_OAUTH_GITHUB_CLIENT_ID / _SECRET).
• HTTP. One tool, invoke: the agent's arguments become the JSON body of a POST to the saved endpoint. You describe the arguments with a bounded JSON Schema so the model knows what to send.
• MCP. A Model Context Protocol server over Streamable HTTP: testing discovers its tools; you choose which of them a run may use.

{  "name": "City lookup",  "kind": "http",  "endpoint": "https://tools.example.com/city",  "credential_id": null,  "description": "Look up city information",  "parameters": {    "type": "object",    "properties": { "city": { "type": "string", "maxLength": 80 } },    "required": ["city"],    "additionalProperties": false  }}

For MCP, kind: "mcp" and the server's endpoint; then POST /v1/integrations/{id}/test, read the discovered tools, and PATCH { "revision", "allowed_tools": ["lookup"] }. Discovery alone grants nothing.

Authentication is a token vault credential referenced by id, whose scope must include the endpoint's exact origin; only bearer tokens are supported — no inline secrets, query credentials, custom headers or OAuth.

Using one in a run

{ "task": "Find the population of the city the page names and add it to the report.", "integration_ids": ["int_…"] }

A schedule's run takes the same field. A continued session keeps its selection and the connections' revisions; omit the field to inherit. A change to a connection, its credential or its discovered tools invalidates the old binding: edit the schedule or start a new session to accept the new configuration.

Status and calls

available is authoritative for new selection. An HTTP test checks reachability (HEAD, a 405 counts), not the endpoint's business behaviour. GET /v1/integrations/{id}/calls lists the latest 50 calls (running, succeeded, failed, unknown); nothing is retried automatically, and an unknown outcome means: check the external system before running again.

Schema subset

type, properties, required, additionalProperties, items, enum, const, description, title, minimum, maximum, minLength, maxLength, minItems, maxItems, anyOf, oneOf. Roots must be objects. $ref, formats, patterns and other keywords fail discovery (tool_schema_invalid).

Management routes (POST, PATCH, DELETE, test, calls) need an owner or admin session; keys read connection metadata and select integrations in runs.