## Recurring MCP Tool Registration Pattern
Every time a new MCP tool is added, developers forget to register it in TWO places:
1. `/rails/mcp-bridge/src/tools/index.ts` - Tool registration
2. `/rails/config/tinker/mcp_permissions.yml` - Agent role permissions
### What Happens
- Developer adds tool to Rails `app/controllers/api/v1/mcp_controller.rb`
- Adds `handle_<tool_name>` method
- Adds tool definition to MCP_TOOLS array
- **Forgets** to add to mcp-bridge TypeScript
- **Forgets** to add permissions to mcp_permissions.yml
### Result
- Tool exists in Rails but agents can't call it
- Not visible in tool list
- Returns "tool not found" errors
### Example Incidents
- Ticket #78: `get_status` tool - missing from mcp-bridge
- Ticket #94: `get_terminal_logs`, `list_agent_sessions` - missing from mcp-bridge
- This has happened 3+ times
### Solution Pattern
When adding a new MCP tool, ALWAYS:
1. Add handler in `mcp_controller.rb`:
```ruby
def handle_<tool_name>(params)
# implementation
end
```
2. Add tool definition to `MCP_TOOLS` array in `mcp_controller.rb`
3. Add to `mcp-bridge/src/tools/index.ts`:
```typescript
{
name: "<tool_name>",
description: "...",
inputSchema: { ... },
execute: async (args: any) => {
const response = await api.post('/mcp/execute', { tool: '<tool_name>', params: args });
return { content: [{ type: "text", text: JSON.stringify(response.data.result, null, 2) }] };
}
}
```
4. Add permissions to `config/tinker/mcp_permissions.yml` for each role that needs it
5. Run tests to verify tool is accessible
### Checklist for Future MCP Tools
- [ ] Handler method in mcp_controller.rb
- [ ] Tool definition in MCP_TOOLS array
- [ ] TypeScript registration in mcp-bridge/src/tools/index.ts
- [ ] Permissions in mcp_permissions.yml
- [ ] Test coverage
