# MCP connectors

Reference configured connectors in your manifest, limit tools, and connect personal accounts.

An agent references a configured connector directly. No catalog association, contract publication,
or connection-selection step is needed.

```yaml title="agent.yaml"
integrations:
  finance:
    connector: global/alphavantage-workspace
    required: true
    tools:
      allow: [SYMBOL_SEARCH, COMPANY_OVERVIEW, EARNINGS]
```

Find the connector and its approved tools:

```bash
tanomis mcp connector list
tanomis mcp connector tools CONNECTOR_ID
```

Use `global/NAME` for a platform connector, `tenant/NAME` for a connector owned by the
agent's workspace, or an exact connector ID. An unqualified name works when unambiguous.
A global agent can reference global connectors; publish a tenant-scoped agent when it needs a
tenant-owned connector. The integration map key is just the agent's local name.

The connector supplies the endpoint, credentials and shared/personal account mode. Personal
connectors still require each caller to connect their own account. Credentials never belong in
the manifest. An optional `identity: workspace` or `identity: user` can assert the expected mode;
it must match the connector.

`tools.allow` is the maximum set the agent may use. Optional `tools.approval_required` lists tools
that require confirmation for each call and must be a subset of `tools.allow`. The connector's
current permitted tools and account access can narrow this set, never expand it.

At registration, the platform records the connector ID and approved tool schemas automatically.
These platform-owned details appear separately from author configuration in the Manifest tab.
Deleting and recreating a connector with the same name does not redirect an existing version.

The gateway checks current access on every tool call. Disabling an agent integration or revoking
a personal credential blocks subsequent calls without waiting for token expiry.

## Changes and availability

- Changing the connector or allowed tools requires a new agent version.
- Rotating credentials on the same connector does not require a new version.
- Changed tool schemas require review and a new agent version.
- **Agent → Integrations** shows the declared connector, readiness and expandable allowed tools.
  Operators can disable or enable access for the agent; they cannot substitute another connector.
- A required connector that is unavailable blocks execution. An unavailable optional connector is omitted.
- Disabled access remains disabled when publishing another version or migrating an old declaration.

Existing catalog-based agent versions remain compatible. New agents should use the direct
connector declaration above. No attachment creation or approval workflow is involved.

## See which agents use a connector

Open **Connectors → a connector → Used by**. Each agent version appears once with its declared tools.

## Read the four independent gates

| Gate | What must be true |
|---|---|
| Manifest declaration | The version names this connector and the requested tool. |
| Connection readiness | The connector is active, approved tool schemas match, and any personal account is ready. |
| Agent access | Access is enabled for this agent and the connector permits the declared tools. |
| Current call authorization | The caller, active run and any required human confirmation permit this exact call. |

  Workspace identity: administrator → workspace connection → connector-owned service authority
  (credential reference when required; none for an unauthenticated endpoint) → manifest-limited
  tool access → external system. Personal identity: member → own account on the declared connector →
  that member’s private credential → manifest-limited tool access → external system.

A member cannot register a custom endpoint through personal sign-in. Platform administrators
manage platform connectors; authorized workspace administrators manage connectors in their workspace.
Neither registering an endpoint nor connecting a personal account overrides the manifest's tool
limits, connector restrictions, an agent disable, or required call approval.

## Resume after connecting an account

If account setup interrupts a request, Console retains the prompt and attachments for up to 24 hours.
Connect your account, return to the saved request, and click **Continue**. Returning from OAuth or
refreshing status does not execute the request automatically. **Discard request** removes it.