> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
docker compose up --build
```

In a separate terminal, run the example:

```bash theme={null}
cd examples/anthropic-tool-use
npm install
npm start
```

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

```bash theme={null}
ANTHROPIC_API_KEY=sk-ant-... npm start
```

## Expected output

Without `ANTHROPIC_API_KEY` (direct invocation):

```text theme={null}
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":"alice@example.com","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`](https://github.com/mishrasanjeev/grantex/tree/main/examples/anthropic-tool-use).