## Custom connectors

The Agen.co connector marketplace includes more than 200 integrations, but every organization has internal tools that aren't on the list. Custom connectors let you bring any internal API, GraphQL service, existing MCP server, or custom code under the same governance layer as your marketplace connectors — with the same policies, approval flows, and audit logs, and no changes to your existing infrastructure.

To access the Custom connectors tab, navigate to **Connectors** in the left sidebar and select the **Custom** tab.

### Connector types

When you click **Add connector** on the Custom tab, a type selection panel opens with four options:

| Type | Best for | How it works |
|  --- | --- | --- |
| **REST** | Internal APIs with HTTP endpoints | Agen.co wraps your REST endpoints as agent-callable tools based on an OpenAPI schema you provide |
| **GraphQL** | APIs built on GraphQL | Agen.co exposes each query and mutation as an individual tool based on a GraphQL schema you provide |
| **MCP server** | Existing Model Context Protocol servers | Agen.co acts as a governance proxy in front of your MCP server |
| **Custom code** | Arbitrary integrations that don't fit a standard API shape | You write the integration logic directly in code |


After creation, custom connectors appear in the **Custom** tab. You can enable or disable individual tools and create policies to control who can invoke them — the same workflow as marketplace connectors.

### REST connector

Select **REST** when you want to expose an internal HTTP API to AI agents.

#### Step 1 — Basic configuration

| Field | Required | Description |
|  --- | --- | --- |
| **Connector name** | Yes | A descriptive name for the connector (e.g., `Internal-HR-API`). |
| **Description** | No | Explains what this connector does and which team or system it belongs to. Shown in the Custom tab to help administrators identify the connector at a glance. |
| **API base URL** | Yes | The root URL of your API (e.g., `https://petstore.swagger.io/v2`). All tool endpoints are resolved relative to this URL. |
| **API timeout (ms)** | No | Maximum time in milliseconds to wait for a response. Defaults to 5000 ms. Increase this for APIs with slower response times. |
| **Custom headers** | No | HTTP headers to include with every request to this API. Pre-filled with `content-type: application/json`. Add authentication headers such as `Authorization` or `x-api-key` here. |


#### Step 2 — API schema

After filling in the basic configuration, you must provide an API schema so that Agen.co can discover the available endpoints and convert them into individual agent tools.

You can either upload a schema file or paste the schema text directly. Accepted formats:

- **OpenAPI 3.x** — JSON or YAML
- **Swagger 2.0** — JSON or YAML


Each endpoint defined in the schema becomes a separately toggleable tool in the connector interface. You can enable only the endpoints you want AI agents to use.

### GraphQL connector

Select **GraphQL** when your internal API uses GraphQL.

#### Step 1 — Basic configuration

The GraphQL form uses the same fields as REST (connector name, description, endpoint URL, timeout, and custom headers). The **API base URL** field accepts your GraphQL endpoint URL (e.g., `https://api.your-company.com/graphql`).

#### Step 2 — GraphQL schema

After the basic configuration, provide a GraphQL schema so that Agen.co can discover the available queries and mutations.

You can either upload a schema file or paste the schema text directly. Accepted format:

- **GraphQL SDL** — `.graphql` files or raw SDL text


Each query and mutation defined in the schema becomes a separate agent tool. This lets you control read operations (queries) and write operations (mutations) independently through policies — for example, allowing all agents to run queries while requiring approval for mutations that modify data.

### MCP server connector

Select **MCP server** when your organization already runs an MCP server and you want to bring it under Agen.co governance.

#### Fields

| Field | Required | Description |
|  --- | --- | --- |
| **Connector name** | Yes | A descriptive name for the connector (e.g., `Internal-Data-MCP`). |
| **Description** | No | Explains what this MCP server exposes and which team or system it belongs to. Shown in the Custom tab to help administrators identify the connector at a glance. |
| **MCP URL** | Yes | The URL of your existing MCP server (e.g., `https://mcp.internal.your-company.com`) |
| **API timeout (ms)** | No | Maximum wait time in milliseconds. Defaults to 5000 ms. |
| **Custom headers** | No | HTTP headers to include with every request. Pre-filled with `content-type: application/json`. |
| **Discover scopes** | No | A helper that connects to your MCP server and retrieves the list of available scopes automatically. Use this instead of entering scopes manually. |


#### Use MCP as auth server

The MCP server connector includes an optional **Use MCP as auth server** toggle. When enabled, Agen.co uses your MCP server URL as the external authorization server instead of its own auth layer.

If your MCP server implements OAuth 2.0 authorization, you can also provide:

| Field | Required | Description |
|  --- | --- | --- |
| **Client ID** | No | A pre-registered OAuth client ID, if your MCP server requires one |
| **Client Secret** | No | The client secret for confidential OAuth clients |


Leave these fields empty if your MCP server handles authorization differently or if you want to rely on Agen.co's built-in governance instead.

#### How MCP server wrapping works

When you add an MCP server connector, Agen.co acts as a proxy between AI agents and your server. Agents never call your MCP server directly — every tool call passes through the Agen.co MCP Gateway first.

This means:

- **No changes to your server** — your MCP server continues running exactly as it is
- **Governance layer applied** — policies, approval flows, and step-up authentication rules take effect for calls routed through this connector, but must be explicitly configured for each tool
- **Anomaly detection and audit logs** — every tool call is logged and monitored the same way as marketplace connector calls
- **Granular tool control** — each tool exposed by your MCP server becomes a separately toggleable item in the connector interface


The MCP server connector wraps your existing server — it does not replace or rebuild it. If your MCP server changes its tool list, the connector will reflect those changes automatically.

### Custom code connector

Select **Custom code** when you need a lightweight custom operation that doesn't justify a full API — for example, a single function that combines calls to multiple services, transforms data before returning it to the agent, or interacts with a system that doesn't expose a standard API schema.

Instead of pointing at an existing API, you write a single tool directly in the portal in TypeScript. The configuration panel has two sides:

- **Left side — tool logic**: A code editor with a function template. The entry point is `onEvent`, which receives a validated input object. If you have attached an existing connector, the function also has access to that connector's OAuth token, so your code can call authenticated APIs without handling credentials manually.
- **Right side — input schema**: A JSON editor where you define the input schema for the tool. The platform validates incoming requests against this schema before passing them to your function.


The function is deployed instantly when you save the connector. It appears as a single tool in the connector interface and is immediately subject to policies, approval flows, and audit logging.

#### Attaching an existing connector

Custom code connectors can be linked to any active connector from your organization's list. This gives your function access to that connector's OAuth token, removing the need to manage authentication credentials in your code manually.

Custom code is the right option for one-off operations that are too specific to justify a full API. For most internal services, the REST or GraphQL connector types are simpler to set up and easier to maintain long-term.

### After adding a custom connector

Once saved, your custom connector appears in the **Custom** tab alongside any other custom connectors you have registered. From there you can enable or disable individual tools and manage the connector configuration.

After saving, the portal prompts you to create a policy before the connector becomes usable. Follow the link to **Policies** and define the access rules for the tools you have just registered. Without a policy, all tool calls are denied by default — the same behavior as marketplace connectors.

Enabling a custom connector is not enough on its own. Tool calls remain denied until you create a policy that grants access to the specific tools you want to expose.

### Next steps

- [Connectors](/agen-for-work/sources/overview) — Manage your full connector list and configure credentials
- [Policies](/agen-for-work/policies/overview) — Create access control rules for your custom connector tools
- [Approval flows](/agen-for-work/approval-flows/overview) — Require human approval before sensitive tools can be invoked