Skip to main content
Agents read your tool names, descriptions and input schemas to decide when to call a tool and what to send. Write them for a reader who has never seen your system.

MCP server

ImpelLabs speaks MCP over Streamable HTTP: JSON-RPC in a POST body. It uses protocol version 2025-06-18. Your server may answer with plain JSON or with an event stream. In a stream, ImpelLabs reads the message that has the id of its request. The calls it makes, in order:
  1. initialize, then the notification notifications/initialized. If your server gives a session id in the Mcp-Session-Id header, ImpelLabs sends it back on later calls.
  2. tools/list. It follows nextCursor until the list ends. It stops at a fixed limit of tools.
  3. tools/call with the tool name and its arguments when an agent calls a tool.
From each tool, ImpelLabs keeps name, title (or annotations.title), description, inputSchema and annotations. A tool with no name is skipped. Your tool’s name is the operation name in ImpelLabs.

Credentials

You may give a key. ImpelLabs sends it as Authorization: Bearer KEY, or in a header you name. The header name must be letters, digits and hyphens, and it cannot be one that the transport sets: accept, content-type, content-length, host, mcp-protocol-version, mcp-session-id, transfer-encoding, connection, cookie or user-agent. A server that asks people to sign in works too: ImpelLabs signs in with OAuth and renews the token before it expires.

Risk from annotations

ImpelLabs sets the risk of a tool from its annotations. A tool is read only when readOnlyHint is true and destructiveHint is not true. Every other tool is write. An admin can change the risk. Set readOnlyHint on tools that only read.

API with an OpenAPI description

Give an OpenAPI 3 or Swagger 2 description as JSON or YAML, up to 5 MB. Give it as text, or as an address that ImpelLabs fetches. Only local $ref values (#/...) are followed. ImpelLabs makes one operation from each get, post, put, patch and delete under paths, up to 300 operations. The base address comes from servers[0].url (variables replaced by their defaults), host and basePath in Swagger 2, or from the address of the description. You can set base_url yourself. It must be an https:// address.

How the input schema is built

  • The schema is plain JSON Schema with additionalProperties: false. required lists path parameters, required parameters and required body fields.
  • References are resolved and allOf is merged. For oneOf and anyOf, ImpelLabs uses the first option.
  • Objects keep up to 64 properties and nest up to five levels. Properties that are readOnly are left out. Enums keep up to 200 values. Property names must match letters, digits, _, . and -, up to 64 characters.
  • A name that clashes gets a number added. The real name goes on the wire.
  • Header parameters named authorization, proxy-authorization, cookie, host, content-length, content-type, transfer-encoding, connection, accept or user-agent are left out. Your credentials set what is needed.

Risk from the method

GET and HEAD operations are read. Every other method is write. An admin can change the risk, and a risk that an admin set stays after a refresh.

Where each input goes

When an agent calls the operation, ImpelLabs sends only the fields that the operation declares. Path fields are URL-encoded into the path, query fields go in the query string, header fields go in headers, and body fields go in one JSON object. A missing path value or a missing required field stops the call before any request is made. The agent gets the message.

Names and keys

Each operation gets the key connector.<connection>.<operation>, built from the connection name and the operation name in lower case with underscores. The key is fixed when the operation is first found. Another operation that makes the same key gets a number added.

Changes that need a review

On refresh, an existing operation goes off, with the reasons saved, if any of these is true:
  • Its risk went up and no admin set the risk.
  • New arguments appeared.
  • Its arguments are no longer described.
  • It now calls another method or path.
An admin turns it on again after the review. New operations start on only when they read. A refresh that lists nothing changes nothing and reports an error.