> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your own tool

> Give your agents a tool you built, as an MCP server or as an API with an OpenAPI description.

You can give your agents tools that run on your own systems. You connect one of two things:

* An MCP server, by its address.
* An API, by its OpenAPI description and base address.

Each tool the server lists, or each operation the description defines, becomes one operation in your workspace. An
agent calls an operation only when you grant it. You connect a tool with your own credentials. ImpelLabs never reads
them from its own settings.

## Connect a tool

Connect in the app under Integrations, or ask your Chief of Staff, which shows a card for you to fill in. You type the
key into the card, never into a chat message. The same steps exist in the API.

**An MCP server.** Send the address, and a key if the server needs one.

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/connectors \
  -H "Authorization: Bearer imp_..." \
  -H "Content-Type: application/json" \
  -d '{"kind": "mcp", "url": "https://tools.yourcompany.com/mcp", "label": "Orders", "key": "YOUR_KEY"}'
```

To find out what a server needs first, call `POST /api/v1/connectors/detect` with `{"url": "..."}`. It answers `none`,
`key` or `oauth`. For a server that asks people to sign in, the app starts the sign-in for you.

**An API.** Send the description as `spec` (an object, JSON or YAML text) or as `spec_url`.

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/connectors \
  -H "Authorization: Bearer imp_..." \
  -H "Content-Type: application/json" \
  -d '{"kind": "openapi", "spec_url": "https://api.yourcompany.com/openapi.json",
       "auth": {"kind": "bearer", "key": "YOUR_KEY"}}'
```

`POST /api/v1/connectors/preview` shows the operations that a description would make, and changes nothing. Set
`base_url` if the description names none. `auth.kind` is `none`, `bearer`, `header` (with `header_name`) or `basic`
(with `username` and `password`). Every address must start with `https://`.

The answer holds the `connection` and a `check` with the operations found. The connection is saved even when the check
fails, so you can see what went wrong.

## Status

| Status | Meaning |
| - | - |
| `connected` | Your server listed its tools, or your API answered a read with these credentials. |
| `unverified` | An API that has no read call without arguments. It is checked at its first call. |
| `pending` | A sign-in is not finished. |
| `failed` | The server or API did not answer, or refused the key. `problem` says why. |

## Turn operations on and grant them

1. New operations that only read start on. Every other new operation starts off.
2. An admin or the connection's owner turns each operation on, and can set its risk: `read`, `write`, `send` or
   `money`. Use `PATCH /api/v1/connectors/{id}/operations` with a body that names each operation key and the fields to change, for example `enabled`.
3. Grant an operation to an agent with `POST /api/v1/connectors/grants` and
   `{"agent_id": "...", "operation": "KEY", "allow": true}`. The change is saved as an edit of the agent.

Your Chief of Staff uses the connections that its person can see, without a grant. Send `"for": "me"` to connect a tool
for yourself only. Without it, only an owner or an admin can connect a tool for the whole workspace. Each connection
needs its own name in the workspace.

The operation key looks like `connector.<connection>.<operation>`. The key is fixed when the operation is first found.

## How an agent calls it

The agent lists its operations with `connector_operations`. It then calls one with `connector_read`,
`connector_write`, `connector_send` or `connector_money`, by the risk of the operation. It passes the operation `key` and
an `input` object that fits the operation's schema. Your workspace rules decide whether the call runs, waits for a
person to approve, or is refused.

## Keep it current

`POST /api/v1/connectors/{id}/refresh` reads the tool list or the description again and checks the credentials. An
operation that is gone from your side is archived. It comes back as it was if you list it again.

If a changed operation now does more, ImpelLabs turns it off until an admin reviews it. See
[Tool contract](https://docs.impellabs.tech/developers/own-tools/tool-contract.md#changes-that-need-a-review).

## Related

* [Tool contract](https://docs.impellabs.tech/developers/own-tools/tool-contract.md) lists what your server or description must provide.
* [Results and side effects](https://docs.impellabs.tech/developers/own-tools/results.md) shows how the agent reads your answer.
* [Security model](https://docs.impellabs.tech/developers/own-tools/security.md) lists what ImpelLabs sends, and to where.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.