Zephr Docs

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 IDMCP nameDescriptionCredential modes
context7context7_callUp-to-date library documentationbyok, hosted
firecrawlfirecrawl_scrapeScrape and crawl web pages to clean markdownbyok, hosted
tavilytavily_searchFast web search returning full page contentbyok, hosted
browserbrowser_renderRender a URL to a viewable browser snapshotbyok, hosted
sentrysentry_queryQuery production errors and issues for debuggingbyok, hosted
githubgithub_apiCall the GitHub API for repos, PRs, issues, and code searchbyok, hosted
linearlinear_searchDeclared in the MCP catalog; outbound adapter not shipped—
supabasesupabase_queryDeclared 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 agent

Credential modes

ModeCredential sourceCost attribution
byokUser's own API key (tools.<tool>.key)provider_cost_micros = actual provider cost
hostedZephr-supplied credentialprovider_cost_micros = 0; charge_micros = retail rate

Band gate

The executor refuses a request before any outbound call when:

  • The installation is degraded or suspended (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_ledger row with operation_kind='tool_call' and model_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 returns not_wired.
  • Each provider has its own rate limits, inherited from the provider's API.
  • The toolBudget in the role's scope binding caps the number of tool calls per session.

Failures and recovery

Failure modes

FailureRecovery
not_wired (local mode)Use BYOK with a local provider SDK, or deploy to cloud
credential_missingSet tools.<tool>.key on the installation
provider_unreachableRetry; the executor writes usage_release / unknown_outcome
degraded / suspendedContact support; the band gate blocks before any outbound call
schema_driftUpdate 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.