# Declare an integration

Reference a connector and its allowed tools directly in agent.yaml.

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.

## 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.