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.
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.
Select REST when you want to expose an internal HTTP API to AI agents.
| 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. |
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.
Select GraphQL when your internal API uses GraphQL.
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).
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 —
.graphqlfiles 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.
Select MCP server when your organization already runs an MCP server and you want to bring it under Agen.co governance.
| 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. |
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.
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.
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.
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.
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.
- Connectors — Manage your full connector list and configure credentials
- Policies — Create access control rules for your custom connector tools
- Approval flows — Require human approval before sensitive tools can be invoked