Connecting your agent

Hone has no dashboard. You read its telemetry through its MCP server, which is mounted at /mcp on your deployment and uses HTTP transport. Every tool is read-only.

There are two ways to connect an agent.

Through Scalpels

If your agent already uses the Scalpels MCP server, it can call Hone without a Hone credential. Create a Scalpels agent token with the Call installed apps ability; see Use Scalpels from your agent. Your agent can then list the MCP-enabled products your team runs, see Hone's tools, and relay a call to your Hone deployment.

Each relayed call carries a short-lived, signed assertion from Scalpels with your identity and your role on the team. Hone verifies that assertion and does not issue its own. The call and its answer pass through Scalpels on the way; see Console for how delegation works and what Scalpels records.

This is the simplest option when you already use Scalpels from your agent, and there is no Hone secret to store.

With a direct MCP credential

To connect an agent straight to Hone, you need an MCP credential minted on your Hone deployment. Hone has no screen for this, so you mint it through Hone's credential API.

Two rules apply to every Hone credential:

• Each credential has one purpose. An ingest credential can only send telemetry; an MCP credential can only read it. Presenting one where the other is expected returns 401.
• An MCP credential reads the whole deployment. It carries no app filter. Every tool can query every app reporting to that Hone deployment. Name it after the team or person who holds it, not after an app.

Mint the credential

Minting needs an operator credential. Create one on the Hone environment with Laravel Cloud's command runner:

cloud command:run <env-id> --cmd="php artisan bfc:install:operator-credential --name='<team>-operator'" -n

Laravel Cloud stores the output of every command it runs, so this operator credential is now retained in Cloud's command history. Rotate it straight away over HTTPS so the retained copy is retired.

To keep the credential out of your shell history and process list, put it in a curl configuration file that only you can read. read -rs does not echo what you paste:

umask 077
printf 'Paste the operator credential: '
read -rs token
printf 'header = "Authorization: Bearer %s"\n' "$token" > ~/.hone-operator.curl
unset token

List your credentials, find the operator row, and rotate it:

curl -s -K ~/.hone-operator.curl -H 'Accept: application/json' https://<your-hone-host>/bfc/credentials
curl -s -K ~/.hone-operator.curl -X POST -H 'Accept: application/json' https://<your-hone-host>/bfc/credentials/<operator-id>/rotate

The rotate response contains the replacement in delivery.secret. Write that into ~/.hone-operator.curl the same way and use it from now on. The old value stops working after a one-hour grace window.

Then mint the MCP credential over HTTPS, so it never appears in Cloud's command history:

curl -s -K ~/.hone-operator.curl -X POST https://<your-hone-host>/bfc/credentials \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d '{"subject_type":"installation","subject_ref":"<team>","kind":"bearer","purpose":"mcp","name":"hone-mcp-<team>"}'

The secret is returned once, in delivery.secret. Hone stores only a hash, so a lost credential is rotated, never recovered. Keep both credentials out of commits, chat messages and tickets. Keep the operator file somewhere you keep secrets, or delete it and mint a fresh operator credential the next time you need one.

Check the endpoint

Before you configure a client, confirm the server answers so you know where a later failure lies. Store the MCP credential in ~/.hone-mcp.curl the same way as the operator credential, then:

curl -K ~/.hone-mcp.curl -X POST https://<your-hone-host>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

A working server answers with "serverInfo":{"name":"Hone","version":"1.0.0"}.

Register it with your agent

For Claude Code, add Hone as a user-level HTTP server so the credential is not written into a project file that could be committed:

claude mcp add --transport http --scope user hone https://<your-hone-host>/mcp \
  --header "Authorization: Bearer <mcp credential>"

This is the one place the credential reaches a command line. Clear the entry from your shell history afterwards, or run claude mcp add without --header and add the header to the hone entry in ~/.claude.json with an editor.

Run claude mcp list to confirm it is reachable, then restart Claude Code. The tools appear as mcp__hone__slow_requests, mcp__hone__list-apps-tool and so on. To remove it, run claude mcp remove hone.

Any other MCP client needs the same three things: the URL https://<your-hone-host>/mcp, the Authorization: Bearer header, and HTTP (not stdio) transport.

Managing credentials

With the operator credential you can manage every credential on the deployment over HTTPS:

If a credential is ever exposed, rotate it. The exposed value stops working when the grace window ends.

Where your telemetry goes

Hone keeps telemetry in your own database. MCP answers, however, go to whichever agent you connect, and they contain app ids, routes, SQL shapes, exception classes and locations, and user ids. If your agent runs on someone else's servers, that is where those answers go.