Hosted tools
Hosted tools are the curated external-provider plane: the only path that opens connections
to metered third-party providers. They are distinct from model-inference lanes (owned by
intelligence-gateway and agent-platform).
Status
Evolving. The MCP tool handlers ship in packages/mcp-server/src/tools/hosted-tools.ts.
The executor boundary (the actual outbound call and metering) is wired through
apps/web/src/lib/cloud/hosted-tools/execute.ts but requires a cloud deployment. In local
mode, hosted tools return a structured not_wired rejection — they fail closed, with no
fabricated metering or provider responses.
Provider status
| Tool ID | MCP name | Description | Credential modes |
|---|---|---|---|
context7 | context7_call | Up-to-date library documentation | byok, hosted |
firecrawl | firecrawl_scrape | Scrape and crawl web pages to clean markdown | byok, hosted |
tavily | tavily_search | Fast web search returning full page content | byok, hosted |
browser | browser_render | Render a URL to a viewable browser snapshot | byok, hosted |
sentry | sentry_query | Query production errors and issues for debugging | byok, hosted |
github | github_api | Call the GitHub API for repos, PRs, issues, and code search | byok, hosted |
linear | linear_search | Declared in the MCP catalog; outbound adapter not shipped | — |
supabase | supabase_query | Declared in the MCP catalog; outbound adapter not shipped | — |
All eight catalog entries are classified as read_only in the mutation surface — they are metered
read-only via tool-proxy; no durable store write is performed.
Setup and configuration
BYOK (Bring Your Own Key)
When tools.<tool>.key is set on the installation, calls use the user's own credential.
The metered cost is the actual provider cost (provider_cost_micros).
{
"tools": {
"firecrawl": {
"key": "fc-..."
}
}
}Hosted credential
When no BYOK key is set, calls use the Zephr-supplied credential. The metered cost is the
published retail rate from query_price_micros.
Tier grants
Hosted tools are assigned tier 'hosted', which is not granted by default. An admin
must add 'hosted' to a role's allowedTiers:
{
"roleId": "role-id",
"allowedTiers": ["core", "search", "docs", "hosted"]
}Data flow
Agent calls zephr_*_search (MCP)
→ Handler validates input against catalog schema
→ Builds ExecutorInput (humanTriggered: false for MCP calls)
→ Injected HostedToolExecutor executes:
1. Load BYOK key from installation settings
2. Resolve entitlement band (ok / soft / degraded / suspended)
3. Reserve usage (usage_reserve)
4. Call external provider (BYOK or hosted credential)
5. Settle usage (usage_settle with provider_cost_micros)
→ Result returned to agentCredential modes
| Mode | Credential source | Cost attribution |
|---|---|---|
byok | User's own API key (tools.<tool>.key) | provider_cost_micros = actual provider cost |
hosted | Zephr-supplied credential | provider_cost_micros = 0; charge_micros = retail rate |
Band gate
The executor refuses a request before any outbound call when:
- The installation is
degradedorsuspended(rejection code:degraded) - The band is below the requested operation's minimum
- The per-tool allowance is exhausted (Free hard-stop, no degradation)
Persistence and security
Persistence
- Metering: every call writes a
usage_ledgerrow withoperation_kind='tool_call'andmodel_revision=<MCP tool name>. - Credential isolation: BYOK keys are stored encrypted in the installation's settings and loaded at request time. Hosted credentials never leave the server boundary.
- No in-band OAuth tokens: tool results never include raw OAuth tokens (ZEP-1879).
- Scope: all calls are scoped to the admitting worktree via the
ToolContext.
Security
- Egress: outbound calls go to the specific external provider's API (api.firecrawl.dev, api.tavily.com, api.github.com, etc.). No other egress is performed.
Limits
- Hosted tools are cloud-only in the sense that the executor lives in
apps/web. In local mode, the handler returnsnot_wired. - Each provider has its own rate limits, inherited from the provider's API.
- The
toolBudgetin the role's scope binding caps the number of tool calls per session.
Failures and recovery
Failure modes
| Failure | Recovery |
|---|---|
not_wired (local mode) | Use BYOK with a local provider SDK, or deploy to cloud |
credential_missing | Set tools.<tool>.key on the installation |
provider_unreachable | Retry; the executor writes usage_release / unknown_outcome |
degraded / suspended | Contact support; the band gate blocks before any outbound call |
schema_drift | Update the MCP tool arguments to match the catalog schema |
Recovery
Apply the matching action in the table, then repeat one status or tool call. Do not retry a suspended entitlement or missing credential until its prerequisite changes.
Troubleshooting
Start with credential_missing, band status, and provider reachability. If those pass, compare the call arguments with the generated MCP catalog before escalating.
What is designed but not shipped
- Local-mode provider routing: the executor boundary is designed to support local provider adapters but currently only wires cloud-hosted execution.
- Provider health dashboard: monitoring per-provider latency and error rates is planned but not implemented.
Related references
- Hosted tools spec — full requirements and scenarios
- Agent runtime — hosted tool tier
- Extensions — extension tool tier (contrast)
- Security and privacy — trust model