Claude Agent SDK - Tool Integration

Working with tools, permissions, and MCP (Model Context Protocol) servers in the Claude Agent SDK.

Tool Permissions

Allowing Specific Tools

import { Agent } from '@anthropic-ai/claude-agent-sdk';

const agent = new Agent({
  allowedTools: [
    'read_file',
    'write_file',
    'list_files',
    'grep',
    'bash',
  ],
});

Blocking Tools

const agent = new Agent({
  disallowedTools: ['bash', 'web_search'],
});

Permission Modes

// Strict mode - requires explicit user approval
const agent = new Agent({
  permissionMode: 'strict',
});

// Permissive mode - auto-approves known safe operations
const agent = new Agent({
  permissionMode: 'permissive',
});

Custom Tools

Defining Custom Tools

import { Agent, Tool } from '@anthropic-ai/claude-agent-sdk';

const customTool: Tool = {
  name: 'get_weather',
  description: 'Get current weather for a location',
  input_schema: {
    type: 'object',
    properties: {
      location: {
        type: 'string',
        description: 'City name',
      },
    },
    required: ['location'],
  },
  execute: async (input) => {
    const { location } = input;
    // Call weather API
    return {
      location,
      temperature: 72,
      conditions: 'sunny',
    };
  },
};

const agent = new Agent({
  tools: [customTool],
});

Tool Execution Context

const customTool: Tool = {
  name: 'read_database',
  description: 'Query the database',
  input_schema: {
    type: 'object',
    properties: {
      query: { type: 'string' },
    },
    required: ['query'],
  },
  execute: async (input, context) => {
    // Context provides agent state and utilities
    console.log('Agent model:', context.model);

    const result = await runQuery(input.query);
    return result;
  },
};

MCP Server Integration

Adding MCP Servers

const agent = new Agent({
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/allowed'],
    },
    git: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-git'],
    },
  },
});

Using MCP Resources

// Agent automatically has access to MCP server resources
const agent = new Agent({
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', './data'],
    },
  },
});

// Agent can now read files via MCP
await agent.chat('Read the contents of data/config.json');

MCP Server Configuration

const agent = new Agent({
  mcpServers: {
    database: {
      command: 'node',
      args: ['./mcp-servers/database.js'],
      env: {
        DATABASE_URL: process.env.DATABASE_URL,
      },
    },
  },
});

Tool Response Handling

Streaming Tool Responses

const response = await agent.chat('List all files in src/');

for await (const chunk of response) {
  if (chunk.type === 'tool_use') {
    console.log('Tool called:', chunk.name);
  }
  if (chunk.type === 'tool_result') {
    console.log('Tool result:', chunk.content);
  }
}

Error Handling

const customTool: Tool = {
  name: 'risky_operation',
  description: 'Perform risky operation',
  input_schema: {
    type: 'object',
    properties: {
      action: { type: 'string' },
    },
    required: ['action'],
  },
  execute: async (input) => {
    try {
      const result = await performOperation(input.action);
      return { success: true, result };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  },
};

Best Practices

Principle of Least Privilege

// Good: Only allow necessary tools
const agent = new Agent({
  allowedTools: ['read_file', 'list_files'],
});

// Avoid: Allowing all tools unnecessarily
const agent = new Agent({
  allowedTools: ['*'],
});

Tool Input Validation

const customTool: Tool = {
  name: 'delete_file',
  description: 'Delete a file',
  input_schema: {
    type: 'object',
    properties: {
      path: { type: 'string' },
    },
    required: ['path'],
  },
  execute: async (input) => {
    // Validate input
    if (!input.path || input.path.includes('..')) {
      throw new Error('Invalid file path');
    }

    // Prevent deleting critical files
    if (input.path.startsWith('/etc') || input.path.startsWith('/sys')) {
      throw new Error('Cannot delete system files');
    }

    await deleteFile(input.path);
    return { deleted: input.path };
  },
};

MCP Server Sandboxing

// Good: Restrict filesystem access to specific directory
const agent = new Agent({
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: [
        '-y',
        '@modelcontextprotocol/server-filesystem',
        './workspace', // Sandboxed to workspace only
      ],
    },
  },
});

Anti-Patterns

Don't Allow Unrestricted Bash

// Bad: Unrestricted bash access
const agent = new Agent({
  allowedTools: ['bash'],
});

// Better: Use specific tools instead
const agent = new Agent({
  allowedTools: ['read_file', 'write_file', 'list_files'],
});

Don't Ignore Tool Errors

// Bad: Silent failure
const customTool: Tool = {
  execute: async (input) => {
    try {
      return await riskyOperation(input);
    } catch {
      return null; // Silent failure
    }
  },
};

// Good: Explicit error handling
const customTool: Tool = {
  execute: async (input) => {
    try {
      return await riskyOperation(input);
    } catch (error) {
      return {
        error: true,
        message: error instanceof Error ? error.message : 'Operation failed',
      };
    }
  },
};

Related Skills

• agent-creation: Agent initialization and configuration
• context-management: Managing agent context and memory