> ## 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.

# The Connection object

> Where we call your backend. Created in the dashboard, referenced by id or name.

See [Connections](/guides/connections) for how to configure one.

## Naming one on a request

| Mode | How |
| - | - |
| Relay | `Patchwork-Connection: <uuid or name>` |
| Direct | the `conn` claim in the session token — a UUID, not a name |

Required when the agent wires a customer patch with no connection pinned to it. Otherwise optional.

## As embedded in a run

```json theme={null}
{ "connection": { "id": "2c5ea4c0-4067-11e9-8bad-9b1deb4d3b7d", "name": "production" } }
```

<ResponseField name="id" type="uuid">
  The connection used for this run.
</ResponseField>

<ResponseField name="name" type="string">
  Its name, unique within your workspace.
</ResponseField>

`null` when the run touched no customer endpoint.

## MCP configuration

Two optional fields, set in the dashboard, that belong to the connection rather than to any agent:

<ResponseField name="mcp_login_url" type="string">
  Your [login bridge](/guides/mcp-login-bridge). Present means published agents on this connection are reachable over [MCP](/guides/mcp); absent means that door is shut for all of them.
</ResponseField>

<ResponseField name="jwks_uri" type="string">
  Where we fetch this connection's public keys. Blank falls back to your workspace key, which is what most integrations want.
</ResponseField>

## Fixed for the life of a run

Once a run resolves a connection, that choice is locked. Resuming a paused run while naming a different connection is refused — a multi-turn conversation must not silently change which of your hosts it is talking to.

## Errors

| Code | Status | When |
| - | - | - |
| `unknown_connection` | `400` / `422` | No connection with that id or name in this workspace. |
| `connection_required` | `422` | The agent has unpinned customer tools and none was named. |
| `connection_mismatch` | `400` / `422` | A resumed run was given a different connection than it started with. |
| `connection_locked` | `400` / `422` | The connection cannot be used for this call. |


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