MCP Tool Development

Adding New MCP Tools

1. Define tool in

   mcp-server/src/tools/[domain]/[tool-name].ts

2. Add to registry in

   mcp-server/src/tools/index.ts

3. Update types in

   mcp-server/src/types.ts

4. Test with Claude Code MCP inspector
5. Document in

   .brief/brief-guidelines.md

6. Add to allowlist in

   .claude/settings.local.json

   if needs preapproval

Tool Structure

export const myTool: Tool = {
  name: 'brief_my_operation',
  description: 'Clear description of what it does',
  inputSchema: {
    type: 'object',
    properties: {
      // Zod-like schema
    },
    required: ['field1']
  },
  handler: async (args, context) => {
    // Implementation
    return { success: true, data: result };
  }
};

Testing MCP Tools

• Use MCP inspector:

  npx @modelcontextprotocol/inspector

• Test error cases (missing params, invalid auth, not found)
• Validate against OpenAPI spec if API-backed
• Test from Claude Code with actual workflows

Documentation Pattern

Update

.brief/brief-guidelines.md

### New Operation Category
- `operation_name` - Description of operation
  - Required params: param1, param2
  - Optional params: param3
  - Returns: what it returns
  - Example: JSON example

Common Mistakes

• ❌ Not validating input schema
• ❌ Not handling authentication errors
• ❌ Not documenting in guidelines
• ❌ Not adding to allowlist if needed
• ✅ Test happy path AND error paths