Anthropic SDK Tool Use

Scope-enforced tool use with audit logging using the Anthropic SDK.

What it does

This example demonstrates the @grantex/anthropic integration by building scope-enforced tools for Claude:

1. Register an agent and obtain a grant token via the sandbox flow
2. Create scoped tools using createGrantexTool with JSON Schema (calendar:read, email:send)
3. Use GrantexToolRegistry to manage tools and dispatch tool_use blocks
4. Invoke tools via client.messages.create() (if ANTHROPIC_API_KEY is set) or directly
5. Demonstrate GrantexScopeError — attempting to execute a tool with storage:delete (a scope not in the grant) throws a GrantexScopeError with requiredScope and grantedScopes properties
6. Inspect scopes offline using getGrantScopes() to decode the JWT without a network call
7. Inspect the audit trail to see the logged actions

Prerequisites

• Node.js 18+
• Docker (Docker Desktop or Docker Engine with Compose)

Run

Start the local Grantex stack from the repository root:

docker compose up --build

In a separate terminal, run the example:

cd examples/anthropic-tool-use
npm install
npm start

To use Claude for real tool use instead of direct invocation, set ANTHROPIC_API_KEY:

ANTHROPIC_API_KEY=sk-ant-... npm start

Expected output

Without ANTHROPIC_API_KEY (direct invocation):

Agent registered: ag_01HXYZ...
Grant token received, grantId: grnt_01HXYZ...
Tools created: read_calendar, send_email (registry has 2 tools)

--- Invoking tools directly (no ANTHROPIC_API_KEY set) ---
Calendar result: {"date":"today","events":[{"title":"Team standup","time":"9:00 AM"},{"title":"Design review","time":"2:00 PM"}]}
Email result: {"sent":true,"to":"[e-mail]","subject":"Today's events","bodyLength":49}

--- Testing scope enforcement ---
GrantexScopeError caught:
  Required scope:  storage:delete
  Granted scopes:  calendar:read, email:send

--- Inspecting grant scopes ---
Scopes in token: calendar:read, email:send

--- Audit trail ---
  [success] tool:read_calendar — 2026-03-30T12:00:00.000Z
  [success] tool:send_email — 2026-03-30T12:00:01.000Z

Done! Anthropic SDK integration demo complete.

Environment variables

Variable	Default	Description
GRANTEX_URL	http://localhost:3001	Base URL of the Grantex auth service
GRANTEX_API_KEY	sandbox-api-key-local	API key. Use a sandbox key for auto-approval
ANTHROPIC_API_KEY	(none)	Optional. Set to use Claude for real tool use

Source code

The full source is in examples/anthropic-tool-use/src/index.ts.