Skip to content

Build a custom connector

Create or adapt a connector for a product that isn’t in the catalog — including your own internal APIs — so your organization can connect accounts and expose MCP tools.

Where to find it: Connectors → Custom (and New connector / Edit from there)

Custom connectors are private to your organization. They work everywhere a public connector does (connections, toolboxes, MCP execution) and still respect restrictions.

Permissions and plan

You need Why
connector:create Author or fork connectors
connector:share Share a custom connector for others to edit (with edit standing on the resource)
Plan feature for custom connectors Gold (and Black); locked plans disable New connector

Built-in Team Admin and above include connector:create. Member does not.

Author vs fork

Path When to use How
Author from scratch Brand-new API or something with no catalog match Connectors → Custom → New connector
Fork Catalog (or another custom) connector is close but needs changes Fork on the catalog/detail row

Forking copies config and documentation into an org-owned custom connector and records upstream lineage so you can pull later. Catalog connectors can’t be edited in place — fork first.

Suggested fork names: {Label} (Fork) and slug {slug}-fork.

Author a connector

  1. Open Connectors → Custom → New connector.
  2. Set Name, optional Category, and Slug (lowercase letters, digits, hyphens; auto-suggested from the name until you edit it).
  3. Edit the connector config JSON: base URL, authorization, credentials, resources/methods, and related settings.
  4. Create the connector, then open Edit to add method documentation (see below).
  5. Save. It appears under Custom, ready for someone to connect an account from Connections.

Documentation editor (methods → tools)

On edit, the method documentation editor turns API methods into MCP tools:

  • A method with a non-empty description is an MCP tool.
  • An empty description is Not an MCP tool — it won’t appear in tool lists for agents.
  • Optionally attach Query and Body JSON Schemas under parameters.
  • The catalog-level description appears on list and detail pages.

Agents choose tools by reading names and descriptions — keep them specific to the job.

Config validation

When you save:

  • Invalid JSON or a non-object config is blocked in the editor.
  • Server validation can return structured, path-qualified errors under Fix these connector config errors: — each line is {path} — {message} (or (root) when there’s no path).

Fix those paths before the connector can be saved successfully.

Edit an existing custom connector

  1. Open the connector (you need edit access) → Edit.
  2. Change identity fields (slug stays locked), catalog description, config JSON, and method documentation.
  3. Save. Existing connections keep working; newly documented methods become tools for toolboxes and MCP.

Delete (blocked while connections exist)

Delete from the connector detail page when you have permission.

The confirm dialog explains that connections already using the connector must be deleted first. If any remain, delete is refused until those connections are removed.

Warning

You can’t delete a custom connector while organization connections still use it. Remove or replace those connections first.

Good to know

  • Custom connectors are org-private; sharing grants view or edit on the definition, not any connected accounts.
  • Fork when you need to customize a public connector without affecting the catalog for everyone else.
  • After you build it, connect accounts the same way as any catalog product: Connections → Add connection.