3. Give it tools

​

Outcome

​

Decide

• Bad: “Give it our Stripe key and the production database URL.”
• Good: “Stripe with a restricted key limited to read on charges, disputes and refunds. Postgres through the support_readonly role that can only see the payments schema views. Zendesk with an agent-level token. Nothing that can move money.”

• A tool provider stores credentials and hands them to the sandbox as environment variables or files, optionally installing a CLI. The agent then uses the vendor’s API, CLI or SDK like an engineer would. Choose this when the vendor has a good API or CLI and you want the agent to write its own queries.
• An MCP server exposes a fixed set of typed tools to the harness. Choose this when the vendor ships an MCP server you trust, or when you want to constrain the agent to a small tool surface.
• Bad: “Add both, the agent will figure it out.”
• Good: “Stripe as a provider because the runbook uses the Stripe CLI for timeline reconstruction. Notion as an MCP server because we only want search and read_page.”

1. CLI. Use the vendor CLI if it covers the job. Declare it as a package on the provider and mise installs it into the snapshot. npm: and github: specs cover most vendors, including CLIs that only ship as GitHub release binaries. A CLI is documented, has --help for the agent to read, and returns structured output.
2. SDK. If the CLI is missing or incomplete, use the vendor’s SDK from a short script. Install it as a provider package when it ships one (for example an npm: spec), or from the repo’s own dependencies.
3. API. If there is no usable SDK, call the HTTP API directly with the credential the provider puts in the environment.
4. Browser. Only as a last resort, when the vendor has no programmatic access at all, use a browser auth method. A person logs in once in a remote browser, the session is saved as Playwright storage state, and the agent drives the web UI with it. This path is the slowest and the most brittle, and it breaks whenever the vendor changes its UI or expires the session.

• Bad: “Use the browser for Stripe, it’s what the team does by hand.”
• Good: “Stripe CLI via github:stripe/stripe-cli for disputes and events, the Python SDK for the one report the CLI lacks, and no browser.”

• Default to an agent-scoped connection: it is used only when a session runs as that agent, it skips the skill filter, and rotating it touches one agent. Use a personal connection only when the work must act as a person, and an org-wide one only when many agents genuinely share one read-only credential.
• An org-scoped connection is available to every template whose skills ask for it. A personal connection is available only to that person’s private sessions: their DMs with an agent and the sessions they open from the dashboard. An agent-scoped connection is available only when a session runs as that agent.
• Bad: “Org-scoped Snowflake with the analytics service account, we already have it.”
• Good: “Agent-scoped Snowflake connection for the risk agent using a role that can read fraud.alerts and fraud.attempts.”

​

How tools reach a session

​

Definition, connection, attachment

​

Credentials go to Runtime, never to an agent

• Bad: “Paste your Stripe key here and I’ll run runtm-api tools create for you.”
• Good: “The Stripe provider is created and required by the refund-investigation skill. Open this link to add the key: https://app.runtm.com/connect?provider=stripe&scope=agent&agent=<agent_id>.”

​

Who the agent acts as: the credential hierarchy

​

How a run picks a credential

1. Agent. If the run is attributed to a roster agent and that agent has its own connection for the provider, it wins. Agent connections are never used by runs that are not that agent’s.
2. Personal, private sessions only. Otherwise, if the session is private (a DM with the agent, or a dashboard session) and its person has a personal connection for the provider, that is used. Team-visible runs skip this step.
3. Org-wide. Otherwise the org-wide connection is used.
4. Unmet. If none exists, the provider shows up as an unmet requirement in the session manifest and the run starts without it.

• Which agent the run belongs to. A Slack mention, a DM, an email, a Linear assignment or a cron tick all run as the agent behind that trigger. A session someone opens from the dashboard runs as no agent, so agent connections never apply to it.
• Whether the session is team-visible or private. A run the agent does in a shared place (a Slack channel or group DM, an email, a Linear or GitHub trigger, a schedule) is team-visible and acts purely as the agent: agent connection, then org-wide, never anyone’s personal credential. This is the same rule GitHub follows: tagged in a channel, an agent opens pull requests as its own GitHub App bot, and a reviewer agent reviews as its own account. A DM with the agent is private to the person in it, so their personal connections can fill in where the agent has none, and on GitHub their commits are authored as them with the agent as co-author. Slack matches the DM sender to a Runtime account by email; a sender with no account falls back to the trigger’s service user, which has no personal connections.

​

The example, run through

​

Where each scope is set

• Org-wide and personal: Settings > Context > Tools & MCP, connect the provider and pick Teams or Personal. Personal connections are visible only to their owner.
• Agent: in the same connect dialog choose the agent scope and pick the roster agent. Agent connections show the agent’s avatar on the connection row. A /connect link with agent=<agent_id> opens the dialog already on the agent scope with that agent selected.
• MCP servers follow the same three scopes on their connection rows, with the same agent, then personal, then org order.

​

Do it

​

Connect a tool provider

1

Open the catalog

Go to Settings > Context > Tools & MCP and click New tool or MCP server. The chooser asks What do you want to add? Pick Tool for a provider or MCP server for MCP.

2

Pick a provider from the catalog

Add a provider lists the built-in providers your org has not added yet: BigQuery, Datadog, Google Cloud, Notion, Phone, PostHog, Slack, Trigify and Zendesk. Pick one and click through to the credentials form.

If the vendor is not in the catalog, create a custom provider instead (next section) and it appears here for everyone in the org.

3

Enter credentials

Fill in the provider’s auth method. Static methods take the fields the provider declares (an API key, a token and email, a service account file). OAuth methods open the vendor’s consent screen. Pick the scope: Personal or Teams.Use the least privileged credential the vendor offers. For Stripe that is a restricted key with read permissions only. For Postgres it is a dedicated read-only role. The agent never needs write access to investigate.

4

Make a skill require it

Open the skill your agent uses (see Skills and runbooks) and declare the provider slug under requires.integrations. Without this the connection is never materialized for the template, unless the connection is agent-scoped.

​

Create a custom provider

{
  "auth_methods": [
    {
      "id": "api_credentials",
      "display_name": "Secret key",
      "kind": "static",
      "fields": [
        {"id": "secret_key", "label": "Secret key", "kind": "secret", "required": true}
      ],
      "materialization": {"env": {"STRIPE_SECRET_KEY": "{fields.secret_key}"}}
    }
  ]
}

​

Add an MCP server

​

Add template secrets

​

Attach repositories

​

Build

​

Verify

1. The tool is connected. Under Tools & MCP the provider shows as connected with a healthy status rather than an error.
2. The template knows about it. The template detail lists the attached skills and MCP servers, and the skill that requires the provider is among them.
3. The build is current. The template build status is ready and it is not flagged as changed since the last build.
4. A session sees it. Launch a session from the template and run env | grep <VAR> in the terminal, or runtm-api session exec <session_id> --json -- env. For an MCP server, ask the harness to list its tools.

​

Gotchas

• Attached after the last build. Attaching a skill or MCP server does not change the running snapshot. attachments_changed_since_build: true on the template means sessions are still booting the old set. Rebuild.
• Connected but not required. An org or personal connection reaches a template only when an attached skill lists the provider in requires.integrations. The unmet requirement shows up in the session manifest as a warning and never blocks boot, so the agent starts and then fails when it calls the vendor.
• Personal key on an org resource. runtm-api tools, mcp and template commands need an org-scoped API key. --org cannot substitute for one. A personal key returns 403 or lists an empty set.
• MCP server without a connection. The server definition is attached and appears in the harness configuration, but every call fails with an auth error because no connection was added. Add one and check it with the connection’s test action.
• Write-capable credentials. Nothing in the platform downgrades a credential. If you connect a full-access Stripe key, the agent has full access. Use the vendor’s restricted keys and database roles, then add allowlist rules for defense in depth (see Guardrails and approvals).
• OAuth providers need the dashboard. runtm-api tools create handles static credentials. OAuth connections are completed in the dashboard because they need a browser. Send the person a /connect?provider=<slug>&method=<oauth_method_id> link (see Credentials go to Runtime, never to an agent).
• A secret pasted to an agent is already leaked. It is now in the transcript, the session history and possibly the model provider’s logs. Rotate it, then have the person connect the new one through a /connect link.
• template create --skip-agent implies --build. The clone-only fast path builds immediately, so anything attached afterwards needs a rebuild. Create without --build when you plan to attach first, then build once.
• Attach merges; --replace overwrites. skills attach and mcp attach add to the existing set. skills import can attach in the same call (--attach-template, --attach-repo, --attach-all); skills create cannot, so create-then-attach is two steps.
• Templates are not only for coding agents. A support agent’s template may clone no repo at all; it exists to carry skills, MCP servers, credentials and guardrails.