Connectors

A connector gives agents tools and data from a system we have no native integration for, through its MCP server or its HTTP API: an internal admin API, a feature flag service, a build system, a data warehouse, an MCP gateway your platform team runs. Connect it once, choose which of its tools agents may call, and Investigations and the agent can query it the way they query everything else. Connectors come in two kinds:

• MCP server: a remote server that speaks the Model Context Protocol and lists its own tools. We discover them when you connect, and re-check as they change.
• HTTP API: any API you can describe with an OpenAPI specification. You supply the spec, and it defines the operations agents can call.

Either way, what agents see is a set of tools with names, descriptions, and arguments. They pick the ones that look relevant, construct arguments from the context they have, call them, and read the results back.

​

How connectors and plugins work together

A connector self-describes through its tool definitions, the way an API reference page describes an API to a person. That’s enough to call the tools. It isn’t enough to use them well in your organization, and that’s what a paired skill adds:

• The connector in the context of your systems. Which pipeline builds which service, where the pipeline definition lives, and which two tools read a failing build down to its first real error.
• How to interpret what the tools return. That a team ID in the flag service is the org ID in every other data source, or that a rule targeting a segment names none of the customers in it.
• When to route to this connector rather than another. That self-hosted tenants in the US have their logs in one connector because of a legacy setup, and everything else is in another.

A connector is the ability to call something. A skill is what says when to call it and what the results mean. Write one alongside every connector you add.

​

Permissions

By default, tools that only read can be called from anywhere our agents run. Tools that make changes run only in Chat or from your team’s MCP clients, never in Investigations. Behind that are three places a tool can be called from: Investigations, running on their own; Chat, where the agent is talking to a person; and MCP clients, where your own team calls it from Claude, ChatGPT, or a coding agent. Which tools may be called from where is decided by a grant policy on each connector, with per-tool overrides where you want them. A request to a tool from a place it isn’t allowed is rejected before it reaches your server.

​

Tool classes

We class every tool from what your server declares about it, and we read the declaration live on each call rather than from a stored copy:

• Read tools carry the readOnlyHint annotation.
• Write tools declare that they make changes, whether or not they’re destructive.
• Unknown tools declare nothing. We treat them as writes, but they get their own policy entry so you can decide how far to trust a server that says nothing.

​

The connector’s policy

A policy has one entry per class, listing where tools of that class may be called from. Every connector starts with our defaults, and an Admin or Owner can change them per connector: Investigations run unattended, so the write policy can never include them. Opting unknown tools into Investigations means treating a server that told us nothing as safe to run without anyone watching, so we leave it off until you turn it on. Because the class comes from the live declaration, a change on your server takes effect at the next call. A tool that was read-only and starts declaring writes moves to the write policy, loses Investigations even if an override names it, and keeps Chat and MCP clients only if the write policy or its override says so.

​

Per-tool overrides

Any tool can be given an explicit set of places to be called from, in place of the policy for its class. Use it to keep one tool narrower than its class, such as a list_jobs tool you only want in Chat, or to allow one unknown tool you’ve checked yourself. An override is remembered until you choose Use connector default on the tool. Syncs and policy changes don’t clear it.

​

Enabling and disabling tools

Every tool also has an on/off switch. A disabled tool can’t be called anywhere, whatever the policy or override says, so it’s the one place to stop a tool without touching permissions. Disabling a tool keeps its override, so switching it back on restores the same decision. When a sync discovers a new tool, read and unknown tools arrive enabled and follow the policy straight away. Write tools arrive disabled, and follow the write policy once an Admin or Owner switches them on. So a new read tool on your server is usable without anyone revisiting the connector, and a new write tool takes one click to switch on.

​

HTTP APIs

HTTP connectors don’t have a grant policy yet. An operation is read-only when it uses GET or HEAD, or when you mark a query-like POST with x-incident-io-read-only: true in the spec. Enabling an operation that makes changes is the decision to allow it.

​

Making tools available to MCP clients

The incident.io MCP server connects your team’s own AI tools to incident.io. Turn on Available to MCP clients on a connector and its tools appear there too, so your team can drive the connected system from Claude, ChatGPT, or a coding agent, under the same policy and with the same tools our agents call. A tool is callable from an MCP client when MCP clients are in its effective grants, from the policy or an override. HTTP operations that make changes can’t be shared to MCP clients.

​

Who can manage connectors

Adding or changing a connector, including its policy and overrides, requires permission to manage connectors, which Admins and Owners hold by default. Any member can see connectors and their usage.

​

Setup

What you’ll need:

• The URL of your server or API. It must use HTTPS and a publicly resolvable hostname, unless you connect through a proxy.
• Credentials for it, as described under the kind you’re connecting below.
• For an HTTP API, its OpenAPI specification as YAML or JSON. Only the operations in the spec can be called, so it’s fine to describe a subset of the API. We use it to construct requests, so operations need paths, parameters, and request bodies to be described.

To add a connector:

1. From Extensions, add a connector and choose MCP server or HTTP API.
2. Enter the URL and credentials. If your server runs on a private network, choose the proxy to reach it through.
3. Test the connection. The server’s tools, or the spec’s operations, are discovered and listed.
4. Review which tools are enabled and the connector’s grant policy, then save.

Once connected, the connector is available immediately, limited to the tools that are enabled and the places its policy allows. You can disable it, or change its policy and overrides, at any time from its page.

​

MCP servers

Connect with the server’s endpoint URL. Two authentication methods are supported:

• Bearer token: a static token we send on every request. Most servers accept it in the Authorization header; you can set a different scheme if yours expects one.
• OAuth: for servers that support it. Register an application with the server’s OAuth provider using https://app.incident.io/auth/telemetry as the callback URL, enter the client ID, and complete the authorization in your browser. If the authorization is later revoked or expires, the connector shows that it needs reconnecting.

If the server publishes its own instructions for how it should be used, we capture those alongside its tools. You can also add context of your own during setup, such as project identifiers, environment names, or default parameters.

​

HTTP APIs

Connect with the API’s base URL and its OpenAPI specification. Authentication is chosen from what you have, or from what the spec declares:

• Bearer token: a token you give us, sent unchanged on every request.
• Basic authentication: a username and password you give us.
• Client credentials: when the spec declares an OAuth 2 clientCredentials flow in its security schemes, the connect form reads the token URL and scopes from it and asks you for a client ID and secret. We exchange them for short-lived tokens as needed.
• Token exchange: for APIs that take a signed assertion and hand back a short-lived token, such as a GitHub App. The spec declares the negotiation with an x-incident-io-token-exchange block on its security scheme, and the connect form asks for the parameters it names, plus the private key used to sign. The key is encrypted and never appears in the spec.

Alongside the spec you can write Guidance: free text for investigation patterns and API quirks the spec can’t express, such as an asynchronous query flow (“create a job, then poll until its status is done”) or a time range dialect the API expects. Leave endpoint lists and parameter schemas to the spec. If the API’s certificate is signed by your own CA rather than a public one, you can supply the CA certificate so we trust it.

​

Private networks

A server that isn’t exposed to the public internet can be reached through a proxy, a lightweight service you run inside your own network that opens an outbound-only encrypted tunnel to incident.io. Choose the proxy when you connect, and an http:// URL is allowed for servers behind it.

​

Monitoring a connector

Each connector’s page shows its connection status and recent usage. When a test or a call fails, the page shows a step-by-step diagnostic of where it failed and what to change, whether that’s a rejected token, an expired OAuth authorization, an unreachable endpoint, or a proxy with no live tunnel. A connector that can’t be reached doesn’t stop a run. The investigation carries on with what it has, and the problem is reported on the connector’s page so a broken connection is visible rather than a silent gap in your investigations. On plans with audit logs, every call an agent makes to a connector tool is recorded as its own entry, naming the connector, the tool, whether it made changes, and the incident it was made for. We also store each call we made and what came back, so you can see what an investigation did and so a call that worked can guide later ones. If that’s a concern for the data a tool returns, disable the tool.

​

Limits

Each call has a timeout of a minute at most, including the time to connect to your server. A tool that takes longer is abandoned and the run carries on without it, so a connector isn’t the way to reach something slow, such as a job that runs for minutes.

​

Best practices

• Keep only the tools you’d want reached during an incident enabled. A shorter list helps an agent pick the right tool rather than the nearest-looking one, and a disabled tool can’t surprise you.
• Make each tool’s description and arguments clear on your server or in your spec. Agents rely on them to decide which tool to call and how, the same way a person reading the tool list would.
• Pair every connector with a skill that explains when to use it and what its results mean. The official skills plugin checks which connectors you have before it drafts one.

​

Related