> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runtm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a KYB provider as a custom tool provider

> Define a know-your-business vendor such as Middesk, Persona or Alloy as a custom tool provider, connect it to one agent only, and require it from the agent's skill. Read when an underwriting or onboarding agent needs verification data that is not in the built-in catalog.

## Outcome

Sessions that run as the underwriting agent have the vendor's API key in the environment and can call the vendor's REST API. No other agent or person in the org receives that key.

## Before you start

* You are an admin of the organization.
* The vendor issues an API key or token. Middesk is used below; Persona and Alloy follow the same steps with their own field and environment variable names.
* The underwriting agent exists on the roster and has a default template with a runbook skill attached.

## Do it

<Steps>
  <Step title="Define the provider">
    In **Settings > Context > Tools & MCP** click **New tool or MCP server**, choose **Tool**, and define a custom provider. Category `custom`, one static auth method with a secret field `api_key`, materialized as `MIDDESK_API_KEY`. Use the vendor's sandbox key while you build.
  </Step>

  <Step title="Connect it to the agent only">
    Open **Add a provider**, pick Middesk, paste the key, and choose the agent scope, then select the underwriting agent. An agent connection is used only by sessions that run as that agent and wins over any personal or org-wide connection for the same provider. The CLI creates only org and personal connections; the agent scope is set in the dashboard, or with `scope: "agent"` and `agent_id` on `POST /api/cloud/knowledge/integrations`.
  </Step>

  <Step title="Require it from the skill">
    Add `middesk` to `requires.integrations` in the agent's runbook skill. Agent connections reach the agent's sessions even without this, but declaring it keeps the requirement visible and lets the same runbook work if you later switch to an org-wide connection.
  </Step>

  <Step title="Teach the runbook the endpoints">
    Put the calls the agent may make in the skill, for example `GET /v1/businesses/{id}` and `GET /v1/businesses/{id}/documents`, and state that the agent never creates or updates a business record. That prohibition becomes a deny rule in step 6 of Build once the agent has passed its seeded cases.
  </Step>
</Steps>

## Verify

Run the agent once from its trigger, or create a session with the agent's id, then read the environment and call the vendor.

A session launched from the same template by a person, without the agent's identity, must not see `MIDDESK_API_KEY` at all. That is the agent scope working.

## Gotchas

* **Wrong scope, wrong runs.** An org-wide KYB key reaches every template whose skill requires `middesk`, including a support agent that has no business reading applications. Keep verification vendors agent-scoped.
* **Sandbox key in production.** The vendor's sandbox key returns synthetic businesses. Swap the connection's credential before the first real run; the provider definition does not change.
* **Rate limits are yours.** The agent calls the vendor API directly. Put the vendor's rate limit in the runbook so a periodic review does not burn the quota.

<Card title="3. Give it tools" icon="plug" href="/build/give-it-tools">
  Custom providers, the three connection scopes, and how a run picks a credential.
</Card>