CLI: Integrations

Integrations extend agents with external capabilities. There are two types: mcp-server (tool access via MCP) and command (a CLI tool with secret injection). Each integration is scoped to an org or agent. The CLI command is valet connectors.

Browse the catalog

List available integration definitions from the Valet-curated catalog:

valet connectors catalog

View details for a specific catalog entry:

valet connectors catalog get <name>

The detail view shows the entry's transport, command, arguments, and required secret slots. Slots that are not required are labeled (optional).

Create from the catalog

valet connectors create <entry> [--agent <agent>] [--org <org>] \
  [--as <name>] [--secret-name <NAME>]

If the first argument matches a catalog entry, provisions an integration using that entry's default configuration. Managed secrets are auto-generated for any secret slots the entry defines. Use --as to give the integration a custom name. OAuth-backed catalog integrations open your browser to the provider's consent screen.

For API-key catalog integrations, set a secret env var beforehand and reference it with --secret-name — its value is forwarded to the provider at connect time, not stored on the integration:

valet env set EXA_API_KEY=exa_live_... --agent my-agent
valet connectors create exa-composio --agent my-agent --secret-name EXA_API_KEY

Create an MCP server integration

valet connectors create mcp-server <name> \
  [--transport stdio|sse|streamable-http] \
  [--command <cmd>] [--args <comma-separated>] \
  [--url <server-url>] \
  [--env KEY=VAL] [--header KEY=VAL]

Use --transport stdio with --command for local processes, or --transport sse/streamable-http with --url for remote servers. Environment variables and headers can reference env vars using the {{NAME}} template syntax instead of embedding literal values — the integration stores the reference, and the control plane resolves it at deploy time. Templates can appear anywhere in a value (e.g. https://{{HOST}}/api).

# stdio transport
valet connectors create mcp-server slack --transport stdio \
  --command npx --args=-y,server-slack \
  --env SLACK_BOT_TOKEN={{SLACK_BOT_TOKEN}} \
  --env SLACK_TEAM_ID={{SLACK_TEAM_ID}}

# SSE transport
valet connectors create mcp-server api \
  --transport sse --url https://example.com/sse \
  --header Authorization={{API_KEY}}

Important: --args takes comma-separated values, not space-separated. Repeat --env and --header for multiple values.

Create a command integration

valet connectors create command <name> \
  --command <cmd> [--args <comma-separated>] \
  [--secrets <comma-separated-secret-names>]

Command integrations wrap CLI tools. The --secrets flag takes a comma-separated list of secret names injected when the command runs. The agent never sees secret values directly.

Naming convention: Name the integration after the CLI command the agent will type. The integration name becomes the executable on the agent's PATH — a wrapper script named after the integration injects secrets and runs the underlying command. If the CLI command is gh, name the integration gh. If the CLI is installed via npx (e.g., npx -y agentmail-cli installs the agentmail command), name the integration agentmail — not the npm package name.

# GitHub CLI — integration name matches CLI command
valet connectors create command gh --command gh --secrets GITHUB_TOKEN

# agentmail CLI (npm package: agentmail-cli) — integration name is the CLI command
valet connectors create command agentmail \
  --command npx --args -y,agentmail-cli \
  --secrets AGENTMAIL_API_KEY

Attach and detach

valet connectors attach <connector-name> [--agent <agent>] [--as <alias>]
valet connectors detach <alias> [--agent <agent>]

Attach an org-scoped integration to an agent. The --as flag lets the agent reference the integration under a different alias — useful when attaching the same integration to multiple agents with different names. Detaching removes the attachment; the org integration itself is not deleted.

Reauthorize an integration

valet connectors reauthorize <name> [--agent <agent>] [--org <org>]

Restarts the OAuth authorization flow for an OAuth-backed integration. Use this to restore an integration whose grant was revoked by the provider or whose first-time authorization never completed. The integration keeps its identity and configuration — only fresh OAuth tokens are issued. The command fails for static-secret and command integrations.

List integrations

valet connectors [--org <org>] [--agent <agent>]

Lists integrations visible to you. Resolution order when no flags are provided: linked agent in the current directory, then the default org.

Integration info

valet connectors info <name> [-a <agent>] [-o <org>]

Shows detailed information about an integration including type, transport, command, args, URL, env (showing {{NAME}} references), headers, secrets (for command integrations), attached agents, and catalog origin.

Destroy an integration

valet connectors destroy <name> [-a <agent>] [-o <org>]

Detaches from all agents and permanently removes the integration. Cannot be undone.

Worked Examples

Set up GitHub for an org

# Set the org secret
valet env set GITHUB_TOKEN=ghp_abc123 --org acme

# Create the GitHub integration from the catalog
valet connectors create github --org acme

# Attach it to an agent with an alias
valet connectors attach github --agent my-bot --as gh

Create a custom stdio integration on an agent

valet connectors create mcp-server my-tool \
  --transport stdio \
  --command npx \
  --args -y,@some/mcp-server \
  --env TOKEN={{MY_TOKEN}} \
  --agent my-agent