A custom connector lets an org admin register an HTTPS API or, where enabled, a Streamable HTTP MCP server that is not in the built-in catalog. It defines the network boundary and authentication method. It does not automatically generate a complete API reference for the agent.
Who configures what
- Org admins create, edit, and delete the connector definition.
- Members connect their own secret or complete the connector's OAuth flow.
- Agent authorization controls which agents can use the connected credential and which named permissions they receive.
The definition is shared in the organization. Member credentials remain scoped to the member and organization.
HTTP API connector
- Open Connectors → Custom and choose New connector.
- Select HTTP API and enter a display name.
- Add one or more HTTPS Prefixes, one per line. A request must match a configured prefix before the connector can authorize it.
- Add authentication if the API needs it:
- API authentication: enter the header name and a header template containing
{{secret}}, for exampleAuthorizationandBearer {{secret}}. - OAuth 2.0: enter the authorization URL, token URL, client ID, client secret, scopes, and token-endpoint authentication method. Register the exact redirect URL shown in the form with the provider.
- API authentication: enter the header name and a header template containing
- Create the connector. Each member who needs it then selects Connect and supplies their secret or completes OAuth.
- Authorize the required agent and permissions.
Changing an existing OAuth definition or its client credentials disconnects current OAuth connections. Members must connect again after the change.
MCP connector
If MCP appears as a connector type in your workspace, enter an HTTPS Streamable HTTP MCP endpoint and configure API or OAuth authentication in the same form. If MCP is not offered in the picker, it is not enabled for that workspace.
Teach the agent the API procedure
A custom connector supplies safe network access and credential injection. The creation form does not upload or auto-discover an OpenAPI document. Give the agent the endpoint, method, parameters, and expected response in the request, or capture that procedure in a workflow with an API reference attached as a file.
Validate a new connector with a narrow, read-only request to a known endpoint. There is no generic Test connection request because many APIs do not expose a meaningful root endpoint.
Security boundaries
- Only HTTPS prefixes and MCP endpoints are accepted.
- The firewall injects the saved credential only into matching requests.
- The saved secret is encrypted at rest and is not exposed to the agent as an environment variable.
- Do not put keys, tokens, or client secrets in chat messages, workflow instructions, or attached files.
- Use a service credential with the minimum upstream scopes needed by the workflow.
Troubleshooting
| Problem | Check |
|---|---|
| New connector is unavailable | Only an org admin can create or edit connector definitions. |
| The agent cannot see the connector | Connect it for the current member, then authorize that agent. |
| The request is blocked before reaching the API | Confirm the request URL begins with one of the configured HTTPS prefixes. |
| The API returns 401 or 403 | Reconnect the member credential and verify the upstream key or OAuth scopes. |
| OAuth returns a redirect error | Register the exact redirect URL shown in the connector form and verify the authorization and token URLs. |
| The agent guesses the wrong endpoint or payload | Put the API procedure in a workflow and attach the relevant reference instead of relying on the connector name alone. |
What's next
- See Workflows for capturing repeated custom-connector work.
- See Permissions for how custom-connector credentials are handled.
- See the Catalog before building custom — your service may already be supported.