# Connecting your tools

How to let your agent act in the external tools and services you already use.

Canonical page: https://kortix.com/docs/guides/connecting-tools

**Connections** (also called connectors) let an agent act in external tools and services on your behalf — Slack, Gmail, a database, any HTTP/GraphQL API. Setup depends on the tool, and you stay in control of what's connected. For the full model, see [Connections](/docs/concepts/connections).

## How a connection works

- **Declared as `connectors` in the manifest.** The `provider` is one of `pipedream`, `mcp`, `openapi`, `graphql`, `http`, `channel` (chat platforms like Slack and Microsoft Teams), or `computer` (a connected machine). The definition lives in git; the credential lives on the platform, never in your repo.
- **Connecting is per project**, like [secrets](/docs/guides/managing-secrets). Connecting a tool for one project doesn't make it available to another.
- **A connector isn't automatically usable by every agent.** Each agent's `connectors` field in the manifest (`all`, `none`, or a list of slugs) grants — or withholds — access to what's connected. Connecting a tool to the project is a separate step from letting a given agent call it.
- **Each tool call can be policed.** A connector's `policies` mark a tool `always_run`, `require_approval`, or `block`.

## Connect a tool

### Open the project's Connectors page

From the dashboard, open the project's Connectors page. For apps Pipedream supports (Gmail, Slack, Stripe, and others — searchable from the same page), use **one-click connect** — it walks you through OAuth and finalizes the connection server-side; no manifest edit required.

For anything else, add a connector by hand: an **OpenAPI** or **GraphQL** API by spec URL, a remote **MCP** server, or a raw **HTTP** API with declared routes.

### Declare it in the manifest (non-Pipedream connectors)

A hand-added connector is a `[[connectors]]` entry:

```toml
[[connectors]]
slug     = "stripe"
name     = "Stripe API"
provider = "openapi"
spec     = "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"

[connectors.auth]
type   = "bearer"
secret = "STRIPE_API_KEY"   # project-secret NAME; value set on the Environment variables page

[[connectors.policies]]
match  = "*.delete*"
action = "block"
```

Pipedream connectors round-trip the same way once connected, but you rarely hand-write them — the dashboard's one-click flow creates the entry for you.

See the [manifest reference](/docs/reference/manifest#connectors--connectors) for every field, and [Connections](/docs/concepts/connections) for how `channel` and `computer` connectors auto-materialize (connecting Slack, Microsoft Teams, or a machine creates their connector for you — no manifest entry needed).

### Set the credential

Where a connector needs a credential (an `auth` block with `type = "bearer" | "basic" | "custom"`), the value is stored on the platform, not in the manifest — set it on the project's Environment variables page, same as any other [secret](/docs/guides/managing-secrets). Pipedream connectors skip this step entirely: they authenticate via the connected account from the one-click flow.

### Grant it to an agent

Connecting a tool to the project doesn't hand it to every agent. In the manifest, each agent's `connectors` field controls what that agent may call:

```toml
[[agents]]
name       = "kortix"
connectors = "all"              # every connector on the project

[[agents]]
name       = "release-bot"
connectors = ["github"]         # only this one, by slug
```

(`kortix.yaml` v2 uses the same field under `agents.<name>.connectors` instead of `[[agents]]` — see the [manifest reference](/docs/reference/manifest#agents-v2).) A *declared* agent with `connectors = "none"` (the default when the field is omitted) can't call any connector, even ones the project has connected. In a v1 project with no `[[agents]]` section at all, this governance layer isn't opted into yet, and every session is capped only by the launching user's role instead.

## Per-call policies

A connector's `policies` gate individual tool calls by name (glob match), independent of which agent is calling:

```toml
[[connectors.policies]]
match  = "*.delete*"
action = "block"            # always_run | require_approval | block
```

Sensitive connectors (email, files, secrets-bearing) default every action to `require_approval` unless a policy explicitly opens it up.

> **Under the hood**
> Every session gets a `kortix-executor` MCP server and a scoped Executor token — the agent discovers tools through it (`connectors` → `discover` → `describe` → `call`), and each `call` is brokered by the Kortix API, which resolves connector identity server-side, enforces the grant and policies, runs it, and audits it. The agent never holds third-party credentials. **Connection profiles** are project-scoped identities behind a connector: one default project-owned profile, plus optional additional profiles that a session can bind explicitly per connector. Profiles hold credentials only for connectors that require them; the legacy manifest `credential = "per_user"` mode is tolerated but resolves to `shared`.