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

# Connectors

> Learn about the unified connector model in the Agentic Framework: the five connector types, the type discriminator, connector auth, and how connectors replace v1 experts.

Connectors are the tools and data sources an agent uses to perform its work. In v2, the Agentic Framework unifies all external integrations under a single connector model. Whether you are attaching a pre-built registry connector, a remote MCP server, another agent, or a custom schema tool, you use the same `connectors` array on the agent.

## What is a connector

A connector is a typed integration attached to an agent. When the agent reasons about a user's message, it selects and invokes connectors to retrieve information, call external tools, or delegate work to other agents.

Every connector shares a common base:

| Property  | Type    | Description                                                                                                                                                                                       |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`      | string  | Server-generated connector identifier (prefixed UUIDv7, e.g. `con.0192f4c8-...`)                                                                                                                  |
| `type`    | string  | The connector discriminator (see below)                                                                                                                                                           |
| `enabled` | boolean | Whether the connector is active for invocations (default: `true`). Only `schema` connectors return this field today; `mcp`, `registry`, `agent`, and `a2a` connectors omit it (treat as enabled). |

Additional properties depend on the connector `type`.

## The type discriminator

Every connector has a `type` field that determines its shape and behavior. The v2 API ships five connector types:

| Type       | Description                                                         |
| ---------- | ------------------------------------------------------------------- |
| `registry` | A pre-built connector from the Corti registry (replaces v1 experts) |
| `mcp`      | A remote MCP server you bring yourself                              |
| `agent`    | Another Corti agent in the same tenant                              |
| `a2a`      | A remote A2A agent discovered by endpoint URL                       |
| `schema`   | A custom tool defined by a JSON Schema                              |

The `type` field is immutable: you cannot change a connector's type after creation. To switch types, remove the connector and attach a new one.

## Connector types

### Registry connectors

Registry connectors are pre-built integrations maintained by Corti and partners. They are the simplest to attach: you reference the connector by its namespaced `name`.

```json theme={null}
{
  "type": "registry",
  "name": "coding-expert",
  "config": {
    "codingSystem": "icd-10"
  }
}
```

| Property | Required | Description                                                             |
| -------- | -------- | ----------------------------------------------------------------------- |
| `type`   | yes      | Always `registry`                                                       |
| `name`   | yes      | Registry connector name (e.g. `coding-expert`)                          |
| `config` | no       | Connector-specific configuration, validated against the registry schema |

<Warning>The `config` field is accepted on create but not yet persisted by the server — it is silently dropped. Configuration will be honored once the feature is fully implemented.</Warning>

Browse available registry connectors via the [registry API](/agentic/guides/use-registry) or the [registry connector catalog](/agentic/registry/overview).

### MCP connectors

MCP connectors connect to remote Model Context Protocol servers you operate yourself. You provide the server URL and optional authentication.

```json theme={null}
{
  "type": "mcp",
  "name": "policybot",
  "url": "https://mcp.example.com",
  "auth": {
    "type": "bearer"
  }
}
```

| Property | Required | Description                                                          |
| -------- | -------- | -------------------------------------------------------------------- |
| `type`   | yes      | Always `mcp`                                                         |
| `name`   | yes      | Display name for the MCP connector                                   |
| `url`    | yes      | MCP server endpoint URL                                              |
| `auth`   | no       | Authentication configuration (see [Connector auth](#connector-auth)) |

<Info>The MCP server must implement the Model Context Protocol. See [MCP protocol](/agentic/v1/mcp-protocol) in the v1 archived docs for protocol details.</Info>

### Agent connectors

Agent connectors delegate to another Corti agent in the same tenant. This enables multi-agent composition: one agent can call another as a tool.

```json theme={null}
{
  "type": "agent",
  "agentId": "agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40"
}
```

| Property  | Required | Description           |
| --------- | -------- | --------------------- |
| `type`    | yes      | Always `agent`        |
| `agentId` | yes      | The target agent's ID |

### A2A connectors

A2A connectors connect to remote A2A agents outside your Corti tenant. You provide the agent's A2A endpoint URL (typically a `.well-known/agent-card.json` location).

```json theme={null}
{
  "type": "a2a",
  "name": "external-research-agent",
  "url": "https://marginalia.polycode.co.uk/.well-known/agent-card.json"
}
```

| Property | Required | Description                                |
| -------- | -------- | ------------------------------------------ |
| `type`   | yes      | Always `a2a`                               |
| `url`    | yes      | Remote agent A2A endpoint URL              |
| `name`   | no       | Optional display name for the remote agent |

### Schema connectors

Schema connectors define a custom tool by providing a JSON Schema. The LLM uses the schema's `name` and `description` to decide when to call the tool, and the schema validates the tool's output shape.

```json theme={null}
{
  "type": "schema",
  "name": "submit_code",
  "description": "Submit the final ICD-10 code with a confidence score.",
  "transition": "complete",
  "schema": {
    "type": "object",
    "properties": {
      "code": { "type": "string" },
      "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
    },
    "required": ["code"]
  }
}
```

| Property      | Required | Description                                                                                         |
| ------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `type`        | yes      | Always `schema`                                                                                     |
| `name`        | yes      | Tool name the LLM calls                                                                             |
| `schema`      | yes      | JSON Schema defining the tool's output shape                                                        |
| `description` | no       | What the tool does; read by the LLM to decide when to call it                                       |
| `transition`  | no       | If set to `complete` or `input_required`, calling this tool terminates the agent loop in that state |
| `enabled`     | no       | Whether the connector is active (default: `true`)                                                   |

<Note>The `transition` field lets you build structured-output agents. When set to `complete`, the agent stops reasoning after the tool is called, validates the output against the schema, and returns the result. No further LLM call is made.</Note>

## Connector auth

Connectors that call external services can authenticate using the `auth` field. Only MCP connectors support `auth` configuration; A2A connectors automatically forward the caller's bearer token. The `ConnectorAuth` schema supports three types:

| Type     | Description                                                   |
| -------- | ------------------------------------------------------------- |
| `none`   | No authentication (default if `auth` is omitted)              |
| `bearer` | Bearer token authentication                                   |
| `oauth2` | OAuth2 authentication with optional `scope` and `redirectUrl` |

For `bearer` and `oauth2`, credentials are provided at call time via the `authorizationData` mechanism.

```json theme={null}
{
  "type": "oauth2",
  "scope": "read:policies",
  "redirectUrl": "https://app.corti.ai/oauth/callback"
}
```

See [Configure connector authentication](/agentic/guides/connector-auth) for a detailed guide.

## Managing connectors

You can manage connectors in two ways:

1. **Via the agent's `connectors` array**: When you create or PATCH an agent, you provide the full `connectors` array. PATCH replaces the entire array wholesale.

2. **Via the connector sub-resource**: You can attach, update, remove, or list individual connectors without rewriting the full agent. The sub-resource endpoints use JSON Merge Patch for updates.

| Operation          | Method and path                                                |
| ------------------ | -------------------------------------------------------------- |
| List connectors    | `GET /v2/agentic/agents/{agentId}/connectors`                  |
| Attach a connector | `POST /v2/agentic/agents/{agentId}/connectors`                 |
| Get a connector    | `GET /v2/agentic/agents/{agentId}/connectors/{connectorId}`    |
| Update a connector | `PATCH /v2/agentic/agents/{agentId}/connectors/{connectorId}`  |
| Remove a connector | `DELETE /v2/agentic/agents/{agentId}/connectors/{connectorId}` |

<Warning>The connector PATCH (update) endpoint is in private preview and returns HTTP 501. To change a connector, remove it and attach a new one. The other sub-resource operations (list, attach, get, remove) are fully functional.</Warning>

See [Manage connectors](/agentic/guides/manage-connectors) for a detailed guide.

## What replaced v1 experts

In v1, the Agentic Framework used three separate concepts: Experts (pre-built specialized agents), MCP servers (remote tool servers), and sub-agents (other Corti agents). v2 unifies all three under the connector model:

| v1 concept | v2 connector type                             |
| ---------- | --------------------------------------------- |
| Expert     | `registry` connector                          |
| MCP server | `mcp` connector                               |
| Sub-agent  | `agent` connector                             |
| (new)      | `a2a` connector (remote A2A agents)           |
| (new)      | `schema` connector (custom JSON Schema tools) |

If you are migrating from v1, see the [migration guide](/agentic/guides/migrate-v1-to-v2) for a detailed mapping.

## Relationship to the registry

The registry is a catalog of pre-built connectors maintained by Corti and partners. Registry connectors are listed and discoverable via the [registry API](/agentic/guides/use-registry). Each registry entry includes:

* A stable `id` (e.g. `coding-expert`)
* A `type` indicating what connector kind it provisions
* A `configSchema` describing accepted configuration
* Capabilities, tags, and documentation links

When you attach a `registry` connector to an agent, you reference it by its `name` (which matches the registry entry's `id`). The platform provisions the connector and validates any `config` you provide against the registry's `configSchema`.

## Next steps

* Follow the [quickstart](/agentic/quickstart) to create an agent with connectors
* Learn how to [manage connectors](/agentic/guides/manage-connectors) via the API
* Browse the [registry connector catalog](/agentic/registry/overview)
* Read about [connector authentication](/agentic/guides/connector-auth)