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

> Scope-enforced tool use, registry, and audit logging for Claude models.

## Install

```bash theme={null}
npm install @grantex/anthropic @grantex/sdk @anthropic-ai/sdk
```

## Scope-Enforced Tools

Create Anthropic tool definitions with built-in Grantex scope enforcement:

```typescript theme={null}
import Anthropic from '@anthropic-ai/sdk';
import { createGrantexTool } from '@grantex/anthropic';

const client = new Anthropic();

const readFileTool = createGrantexTool({
  name: 'read_file',
  description: 'Read a file from disk',
  inputSchema: {
    type: 'object',
    properties: { path: { type: 'string', description: 'File path' } },
    required: ['path'],
  },
  grantToken,                 // JWT from Grantex token exchange
  requiredScope: 'file:read', // must be in token's scp claim
  execute: async ({ path }) => {
    return await fs.readFile(path as string, 'utf-8');
  },
});

// Pass definition to Claude
const response = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  tools: [readFileTool.definition],
  messages: [{ role: 'user', content: 'Read config.json' }],
});

// Handle tool_use blocks
for (const block of response.content) {
  if (block.type === 'tool_use') {
    const result = await readFileTool.execute(block.input as { path: string });
  }
}
```

`execute()` verifies the token signature and claims with `verifyGrantToken()` before checking its verified `scp` claim. The verifier may contact its configured JWKS endpoint to resolve keys, so that endpoint must be reachable. Invalid tokens and missing scopes fail before your function runs.

## Tool Registry

Use `GrantexToolRegistry` to manage multiple tools and dispatch `tool_use` blocks by name:

```typescript theme={null}
import { createGrantexTool, GrantexToolRegistry } from '@grantex/anthropic';

const registry = new GrantexToolRegistry();
registry.register(readFileTool);
registry.register(writeFileTool);

// Pass all definitions to Claude
const response = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  tools: registry.definitions,
  messages,
});

// Dispatch tool_use blocks
for (const block of response.content) {
  if (block.type === 'tool_use') {
    const result = await registry.execute(block);
  }
}
```

## Inspect Grant Scopes

Decode the scopes from a grant token without verification. Use this only for display or debugging; authorization decisions must use the verified tool wrapper:

```typescript theme={null}
import { getGrantScopes } from '@grantex/anthropic';

const scopes = getGrantScopes(grantToken);
// ['file:read', 'file:write']
```

## Audit Logging

### Wrap a tool

```typescript theme={null}
import { Grantex } from '@grantex/sdk';
import { withAuditLogging } from '@grantex/anthropic';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const audited = withAuditLogging(readFileTool, grantex, {
  agentId: 'ag_01ABC...',
  agentDid: 'did:key:z6Mk...',
  grantId: 'grnt_01XYZ...',
  principalId: 'user_01',
});
// audited.execute() logs success/failure automatically
```

### Handle a tool\_use block directly

```typescript theme={null}
import { handleToolCall } from '@grantex/anthropic';

for (const block of response.content) {
  if (block.type === 'tool_use') {
    const result = await handleToolCall(readFileTool, block, grantex, {
      agentId: 'ag_01ABC...',
      agentDid: 'did:key:z6Mk...',
      grantId: 'grnt_01XYZ...',
      principalId: 'user_01',
    });
  }
}
```

## API Reference

### `createGrantexTool(options)`

| Option | Type | Description |
| - | - | - |
| `name` | `string` | Tool name (matches `^[a-zA-Z0-9_-]+$`) |
| `description` | `string` | Description shown to the model |
| `inputSchema` | `JsonSchema` | JSON Schema for tool input |
| `grantToken` | `string` | Grantex JWT from token exchange |
| `requiredScope` | `string` | Scope required to invoke this tool |
| `execute` | `(args: T) => Promise<unknown>` | Tool implementation |

Returns `{ definition, execute }`.

### `GrantexToolRegistry`

| Method | Description |
| - | - |
| `register(tool)` | Register a tool (chainable) |
| `definitions` | All registered Anthropic tool definitions |
| `execute(block)` | Execute a tool from a `tool_use` block |

### `withAuditLogging(tool, client, options)`

Returns a wrapped `GrantexTool` that automatically logs success/failure to the audit trail on every `execute()` call.

| Option | Type | Description |
| - | - | - |
| `agentId` | `string` | Agent ID for audit attribution |
| `agentDid` | `string` | Agent DID (e.g. `did:key:z6Mk...`) |
| `grantId` | `string` | Grant ID for the session |
| `principalId` | `string` | Principal ID that granted authorization |

### `handleToolCall(tool, block, client, options)`

Same options as `withAuditLogging`. Executes the tool with `block.input` and logs the result.

### `getGrantScopes(grantToken)`

Returns `string[]` — the scopes from the token's `scp` claim.

### `GrantexScopeError`

Thrown when a grant token is missing a required scope.

| Property | Type | Description |
| - | - | - |
| `requiredScope` | `string` | The scope that was required |
| `grantedScopes` | `string[]` | The scopes the token actually has |

## Requirements

* Node.js 18+
* `@grantex/sdk` >= 0.1.0
* `@anthropic-ai/sdk` >= 0.30.0

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).

## Current Authority and Human Identity

Use the exact integration version and minimum primary SDK in [Release Status](/release-status).
Per-invocation issuer authority and trusted principal/agent binding are opt-in.
Configure the callback with the trusted issuer and derive identity from the host's
authenticated session; signature and scope checks alone do not prove current
revocation or human consent. See [SDK execution authority](/guides/sdk-execution-authority)
for configuration, denial behavior and manifest/decision/caps boundaries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.