Administer

Connectors

What a connector is#

A connector gives agents and artifacts access to another service's tools, such as HubSpot, Google Drive or an MCP server your company runs. You set it up once, with the credential it needs, and Valet supplies the credential on each call.

Agents and artifacts can hold connectors. An app can't; it reads keys from env vars.

Kinds of connectors#

• Remote MCP server. An MCP server Valet reaches over HTTP.
• Built-in integration. A service's API that Valet serves as an MCP server of its own: Google Workspace (Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, Contacts and Forms), QuickBooks Online, X, Luma and Formlabs.
• Local MCP server. An MCP server that runs as a process (stdio), usually an npm or Python package.
• Command. A command-line tool, such as gh or aws, that the agent runs.

Scope and attachment#

A connector belongs to the organization or to one agent. An organization connector holds one credential for the whole organization and does nothing until you attach it to agents or artifacts. An agent connector belongs to one agent, and only that agent uses it.

Attaching gives the holder every tool the connector exposes.

• An agent calls the tools on its own, including when nobody is watching. Attaching or detaching restarts a running agent. If any of an agent's connectors fails to start, the agent doesn't start. An agent holds at most one connector per catalog entry.
• An artifact calls the tools from the page's JavaScript, through Valet. Everyone who can open the page can call every tool, with the organization's credential. An artifact holds only organization connectors that are remote MCP servers or built-in integrations. Valet refuses these calls from a public artifact, and allows 60 a minute per artifact by default.

The catalog#

Valet's catalog lists more than 150 connectors you can add without writing any configuration:

• Curated entries: Valet's built-in integrations, remote MCP servers that vendors run, and local MCP servers and commands.
• Composio entries: apps reached through Composio, a third-party service. Composio holds the account's credential and runs each tool call.

list_catalog_connectors

Add a connector from the catalog#

Add an organization connector from the dashboard's Integrations section, with the CLI, or by asking a coding agent that uses Valet's MCP server. Each entry takes its credential in one of three ways:

• Sign-in. You authorize in a browser, and Valet stores the token.
• API key. You enter a key, and Valet stores it as an organization secret.
• Composio. You connect the account through Composio.

Create the connector with its key, then attach it to the agents and artifacts that use it:

create_connector
{ "entry": "luma-mcp", "secrets": { "LUMA_API_KEY": "secret-..." } }

attach_connector
{ "name": "support-bot", "connector": "luma-mcp" }

attach_connector
{ "name": "events", "connector": "luma-mcp" }

Valet stores the key as an organization secret, named for the connector. Creating an API-key connector fails until its key is set, and the error names what's missing.

A key passed to create_connector passes through the conversation. To keep it out, enter the key in the dashboard's Integrations section, or set it yourself with valet env set as shown. For a sign-in or Composio entry, create_connector sends you to the Integrations section, and valet connectors create opens your browser and waits.

Add your own MCP server#

Any MCP server reachable over HTTP can be a connector, including one your company runs. Add it in the dashboard's Integrations section or with the CLI. Pass a key as a header that references a secret, so the value never appears in the connector:

For a server that uses OAuth, leave out the header. Valet discovers the server's authorization endpoints, registers itself as a client, and opens your browser. The server must support dynamic client registration; Valet refuses an OAuth server that doesn't.

Add local MCP servers and command connectors with the CLI:

Credentials#

How Valet stores them#

Valet encrypts every credential before it stores it: keys, header values, and OAuth access and refresh tokens. It never returns an OAuth token, and it masks header values when it shows a connector.

A key you enter for an organization connector is an organization secret env var. Any organization member can reveal it on the connector's page in the Integrations section. Apps receive organization env vars in their environment, secrets included, so every app in the organization can read it.

What agents and artifacts see#

• Remote MCP servers and built-in integrations. The agent holds only a proxy token. It names one connector and one agent, expires on its own, and stops working when you remove the connector. Valet's proxy checks it, looks up the credential, and adds it to the request. An artifact's page holds no token; the visitor's session admits the call.
• Local MCP servers and commands. These run in the agent's runtime, so the secret goes there. Valet hands it only to the connector's process, which runs as a separate user: the agent can run the command but can't read its secret. A command that prints its own credential, such as gh auth token, still shows it to the agent.
• Composio entries. Composio holds the credential and runs each call.

A connector can do anything its credential allows. Give it a key with the least access the work needs.

Who the credential represents#

A connector acts as whoever authorized it. Every agent and artifact that holds an organization connector uses its one credential, and so does every person who opens an attached artifact. A Gmail connector authorized by one person reads that person's mail for everyone who uses it. Valet doesn't sign each viewer in to the service separately.

Reauthorizing#

Valet refreshes an OAuth token when the service rejects an expired one. When a service revokes a grant or rejects a key, Valet marks the connector as needing attention. The Integrations section shows it, and valet connectors info prints the status and the service's reason.

reauthorize_connector
{ "connector": "hubspot-mcp" }

reauthorize signs in again and keeps the connector and its attachments. It works for sign-in and Composio connectors; for a key, set a new value with valet env set.

Supply-chain controls#

Local MCP servers and commands run code in the agent's runtime. Valet limits that code three ways:

• npm and uv pick only releases published 7 or more days earlier, so a malicious release has time to be found and pulled. The rule holds for packages Valet installs ahead of time and for packages fetched when an agent starts.
• A command is a plain name, such as gh or npx, never a path. Valet runs only programs installed with the runtime, so an agent can't run a program it wrote as a connector.
• Valet installs most catalog packages ahead of time. Others download when the agent starts.

These controls don't limit what an installed program does with its arguments: a command connector that runs bash can run anything. The 7-day rule covers npm and uv only.

Who can manage connectors#

Valet has no separate administrator role. Every organization member can add, attach, detach, reauthorize and remove the organization's connectors. So can an agent that holds the catalog's valet connector, which acts for the organization.

The Integrations section also shows which agents and artifacts hold each connector. destroy_connector refuses while anything holds the connector; valet connectors destroy removes it and detaches it from everything that holds it.