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

# Connections

> A named host we call when the agent uses one of your tools, plus how we authenticate when we get there.

A connection answers two questions: **where** do we send a request, and **what credential** do we present. Create one under **Connections** in the dashboard.

| Field | Meaning |
| - | - |
| `name` | Unique within your workspace. Usable in place of the id in relay. |
| `base_url` | The host we call. Patch routes are resolved against it. |
| `auth` | How we authenticate to you: `none`, `static`, or `minted`. |
| `mcp_login_url` | Optional. Your [login bridge](/guides/mcp-login-bridge). Setting it opens the [MCP door](/guides/mcp) on agents using this connection. |
| `jwks_uri` | Optional. A signing key for this connection alone. Blank means your workspace key, which is the usual case. |

## Egress auth modes

<ParamField path="none" type="mode">
  No credential. For endpoints that are public or protected some other way.
</ParamField>

<ParamField path="static" type="mode">
  A long-lived bearer token you store on the connection. Simple, and the same for every subject — your endpoint cannot tell one of your users from another, so the token's own authority applies.
</ParamField>

<ParamField path="minted" type="mode">
  We fetch a short-lived token per subject from your `mint_url`, then present it. Your endpoint verifies it, reads `sub`, and runs its own per-user authorization unchanged. This is the mode that keeps the subject's authority intact end to end.

  A connection declares one mint URL, and it must handle both callers — see [The mint endpoint](/guides/mint-endpoint). If it only handles your browser, the [Playground](/guides/playground) cannot drive this connection.
</ParamField>

A connection set to `static` must carry a bearer token; one set to `minted` must carry a mint URL. Validation enforces both.

## Two secrets, two jobs

They are easy to conflate and must never collapse into one:

| Secret | Answers | Lives on |
| - | - | - |
| **Request secret** | "Is this really Patchwork?" | The workspace |
| **Minted token** | "Is this a real grant from a real subject?" | Per subject, per request |

If we held both, we could answer both ourselves — which would make us able to mint identities. Keeping them separate is what makes an intercepted session token useless on its own. See [Signing and verification](/guides/signing).

## Opening the MCP door

A connection with an **MCP login URL** makes every published agent that uses it reachable from your users' own AI clients. The URL is a page you host that authenticates your user and signs their subject back to us; identity is the only thing [MCP export](/guides/mcp) asks of you.

It sits on the connection rather than the agent because identity belongs to the backend. Agents on different connections can serve different user pools; agents on the same one share it.

## Choosing a connection at request time

An agent can pin a connection, or leave it open and take one per request:

* **Relay** — `Patchwork-Connection: <uuid or name>`
* **Direct** — the `conn` claim in the session token, which must be a UUID

If the agent wires a customer patch with no pinned connection and none is supplied, the call fails with `422 connection_required`.

Once a run has a connection, it is fixed for that run. Resuming a paused run with a different connection is refused — otherwise a multi-turn conversation could silently change which of your hosts it was talking to.

## Testing one

Press **Test** on a connection. We POST a signed nonce to `/patchwork/up` on your host and check for a proof only computable with the shared request secret.

| Result | Meaning |
| - | - |
| `verified` | We reached you and the proof matched. Your secret is correct. |
| `reachable` | We reached you but got no valid proof. Endpoint missing, or secret mismatch. |
| `unreachable` | Wrong URL, TLS failure, or firewall. |

Only `verified` means the trust is wired correctly. A bare `ok` cannot pass — it cannot fake the proof.


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