HooshyarDocs

MCP servers

Hooshyar has two MCP servers. They do different work and use different credentials.

MCP servers

ServerAddressCredentialUse it to
Company tools: the gateway's /mcphttps://gateway.example.com/mcpHOOSHYAR_API_KEYuse company tools from an agent
The admin MCP serverhttps://mcp.example.com/mcpHOOSHYAR_TOKENread and change the gateway configuration

Company tools: the gateway's /mcp

  • Your client must speak MCP revision 2026-07-28. The gateway refuses an older client.
  • You see only the tools that your key can use. A tool that writes waits for the approval of an administrator.
  • Add ?disclosure=progressive to the address to see only the search tools. Use this when the list of tools is long.

The configuration

json
{
  "mcpServers": {
    "hooshyar": {
      "type": "http",
      "url": "https://gateway.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${HOOSHYAR_API_KEY}"
      }
    }
  }
}
url
https://gateway.example.com/mcp?disclosure=progressive

A virtual server

An administrator can make a virtual server: a smaller set of tools at its own address. Use the same key.

json
{
  "mcpServers": {
    "hooshyar": {
      "type": "http",
      "url": "https://gateway.example.com/mcp/<server-id>",
      "headers": {
        "Authorization": "Bearer ${HOOSHYAR_API_KEY}"
      }
    }
  }
}

The admin MCP server

An agent can read the configuration, usage and status, and suggest changes that you approve. The server checks each call against the token.

Warning: do not write the token in the configuration file. Teams often commit an MCP configuration, for example a project .mcp.json. Every example reads the token from HOOSHYAR_TOKEN in your environment. If your client does not expand ${…}, use the secret input of the client.

Claude Code

Where: .mcp.json in a project (shared with the team), or user scope via the CLI

Limit: Claude Code gets READS ONLY over this endpoint. Its MCP client speaks MCP 2025-11-25 (verified against v2.1.212 on 2026-07-30), and that revision cannot carry the operator-confirmation step a write needs, so the write tools are not offered to it — the server says so in its instructions rather than leaving the agent to guess. Config, models, usage and the config.validate dry run all work. For writes, use the local path at the bottom of this page; it serves both revisions.

bash
claude mcp add --transport http hooshyar https://mcp.example.com/mcp \
  --header "Authorization: Bearer ${HOOSHYAR_TOKEN}"
json
{
  "mcpServers": {
    "hooshyar": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${HOOSHYAR_TOKEN}"
      }
    }
  }
}

The CLI form writes the same entry without hand-editing JSON. Prefer it for user scope, where the config is not committed.

Cursor

Where: ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)

json
{
  "mcpServers": {
    "hooshyar": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${HOOSHYAR_TOKEN}"
      }
    }
  }
}

Cline (VS Code)

Where: cline_mcp_settings.json, via the MCP Servers pane

json
{
  "mcpServers": {
    "hooshyar": {
      "type": "streamableHttp",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${HOOSHYAR_TOKEN}"
      }
    }
  }
}

Cline has spelled the transport key differently across versions — if it rejects streamableHttp, check its MCP docs for the spelling your build expects. The URL and the header are the same either way.

Any other client

Where: wherever it keeps MCP servers

json
{
  "mcpServers": {
    "hooshyar": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${HOOSHYAR_TOKEN}"
      }
    }
  }
}

At the wire level nothing is client-specific: POST JSON-RPC to the URL with Authorization: Bearer, and Accept: application/json, text/event-stream (a reply may be either). Protocol revision 2026-07-28.

Over HTTP, a client on the 2025 MCP revision gets the read tools only. It cannot show an approval prompt, so the server does not offer the write tools. To write configuration from this client, use the local path below. If a client does not connect, docker compose logs mcp on the server gives the reason.

Check the connection

Ask the agent "who am I on the gateway?". It calls auth.whoami and gives the name and the role of the token. A 401 means that the server refused the token. A 403 on one tool is correct: the role of the token does not include that operation. This command checks only that the server runs. It needs no token:

bash
curl https://mcp.example.com/healthz

Run it on your computer

Use this path to write configuration from a client on the 2025 MCP revision. The token stays in a file on your computer. The client configuration holds no token and no address.

bash
npx hooshyar-mcp login --url https://console.example.com
json
{
  "mcpServers": {
    "hooshyar": {
      "command": "hooshyar-mcp"
    }
  }
}

A client starts the server without your shell, so it often does not find hooshyar-mcp on its PATH. If the client cannot start the server, give the full path of the file.

The admin tools

Each tool is one operation of the Admin API. An agent must get your approval before it calls a tool marked confirm.

ToolWhat it doesApproval
alerts.channels.listList the budget alert channels. A webhook target is masked; the URL is a secret.none
audit.listList audit-log entries, newest first: who changed what, when, and the before and after.none
auth.whoamiDescribe the calling principal and the operations it is allowed to call.none
batches.listList batch jobs, newest first, each with its per-model usage ledger and deferred cost.none
config.generations.listList the routing-config history, newest first: one entry per change to the document.none
config.generations.readRead one past routing-config state as a document, ready to validate and apply back.none
config.readRead the routing config as a declarative, round-trippable document.none
config.utterances.readRead one route's classifier examples. 404 for an unknown route.none
config.validateDry-run a config document: diagnostics plus a structured diff against the live config.none
connections.listList every upstream connection: whose it is, the provider, scopes, state and last use. Never a token.none
connections.providers.listList the OAuth providers a person may connect an account at, with their endpoints. Never the client secret.none
credentials.listList provider credentials: name, provider and endpoint. Never the provider key.none
credentials.usageRead each provider credential's usage in its limit window, as tokens, USD and percent of the limit.none
guardrails.activityCount the requests each guardrail rule acted on, per stage and action, over a window (default: 30 days).none
guardrails.readRead the screening rules: the master switch, every rule with its scope and mode, soft-deny and stream screening.none
keys.listList client keys with their owner, route and ZDR fences, tool grant, team, budget and spend. Never a secret.none
logs.listList recent request-log rows, newest first: route, key, model, status, latency, tokens and cost. Never a body.none
model-policy.listList the per-model zero-data-retention attestations that ZDR-only keys and routes are routed on.none
models.catalogList the routable models with their provider model, credential and source.none
models.listList the chassis model catalog — the valid targets for a route.none
observability.metricsRead daily request, token, cost and latency trends from Langfuse over a window (default: 14 days).none
observability.traces.listList Langfuse traces (names, timings, costs, tags), filtered by window, user, tag or name. Never a body.none
packs.listList the context packs: access policy, published and retired versions with their hashes, assignments and the settings. Never a version's text or a draft.none
prices.listList the rates the gateway prices each request with, per model, and where each rate came from.none
providers.listList the providers and models the chassis registry knows, for choosing a model to add.none
reports.agent-metricsReport the usage the agents reported themselves, per client, model, person, session, key or user. Never spend.none
reports.developersReport each developer's Claude Code usage from the client's own telemetry. Estimates, never spend.none
reports.economicsRead cost economics: spend per client, model and tool, with the driver decomposition and the subscription lane.none
reports.executiveRead the executive summary: spend, traffic, latency, top routes and models, and credit alerts.none
reports.hooksReport what the managed Claude Code hooks decided: denials, unscreened work and screening outages.none
reports.listList the reports the caller may open: built-in, their own, and shared with their role.none
reports.providersReport spend per provider credential, against its declared limit, with live rate-limit headroom.none
reports.readRead one report's definition: a built-in id, or a saved report's uuid the caller may see. The question, never the figures.none
reports.runRun one report (a built-in or saved report by id, or a draft spec) for the caller.none
reports.securityReport security events: refused and failed requests, and the security-relevant audit entries.none
reports.teamReport usage per person, rolled up through key ownership, with an unassigned bucket.none
reports.tool-callsReport tool calls through /mcp per tool, server, person or key: calls, outcomes, refusals, cost and latency.none
retention.readRead the retention policy (days kept per table; 0 = forever) and the last purge pass.none
skills.listList the company skills: who may select each, and every published or retired version's title, digest and declared requirements. Never a procedure's text, a draft or a review comment.none
status.readRead each catalog model's health: up, degraded, down or unknown, with recent traffic, errors and latency.none
subscription-lane.readRead whether a claude.ai subscription credential may cross the gateway, and what each mode does.none
teams.listList the teams a key may be put in, each with its tool grant and its member count.none
tools.calls.listList tool-call ledger rows, newest first: person, tool, decision, outcome, latency and cost, refused calls included. Never arguments or results.none
tools.groups.listList the tool groups: named bundles of servers, tools, resources and prompts that a grant may name.none
tools.servers.inspectInspect one registered server from stored facts only: which grants reach it, its recent ledger activity and its name collisions.none
tools.servers.listList the registered MCP and REST servers with every tool, resource and prompt they declare. Never a credential.none
tools.variables.readRead a service-account key's server variables (a site, a workspace id), per server that declares them. Never a secret.none
tools.virtual-servers.listList the virtual servers: named toolsets an agent mounts as one endpoint. A mount only narrows a grant.none
usage.reportAggregate request usage grouped by one dimension over an optional date range.none
usage.seriesRead usage per hour or day: requests, tokens, cost, and latency and time-to-first-token percentiles.none
usage.spend-splitRead interactive and batch spend for one window, side by side. Only the money is added up.none
users.directoryList the accounts that can own a key: id, name and email only. Disabled accounts are left out.none
users.listList console users with their role, status, identity provider and last sign-in.none
alerts.checkEvaluate every budget against the alert bands now, and deliver each new crossing once. Safe to repeat.confirm
config.route.deleteDelete one route and its utterance examples.confirm
config.route.upsertCreate or update one route (model, fallbacks, params, enabled).confirm
config.settings.updateUpdate the default route and/or the classifier settings.confirm
config.utterances.setReplace one route's classifier examples. The gateway rebuilds its embedding index. 404 for an unknown route.confirm
guardrails.testScreen a sample against the rules for a route, key and tags, storing nothing. Budgeted per caller (429); each trial is audited without its text.confirm
reports.saveSave a report for the caller: create one, or replace one they own. It stores the question, never the figures.confirm