# Add Tools

> Add tools to your agent and grant required permissions in databricks.yml. Use when: (1) Adding MCP servers, Genie spaces, vector search, or UC functions to agent, (2) Permission errors at runtime, (3) User says 'add tool', 'connect to', 'grant permission', (4) Configuring databricks.yml resources.

- Skill: `databricks/add-tools-4` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add databricks/add-tools-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/databricks/add-tools-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: databricks (https://skillmd.com/u/databricks)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/databricks/add-tools-4

---


# Add Tools & Grant Permissions

**After adding any MCP server to your agent, you MUST grant the app access in `databricks.yml`.**

Without this, you'll get permission errors when the agent tries to use the resource.

## Workflow

**Step 1:** Add MCP server in `src/mcp-servers.ts`:
```typescript
import { DatabricksMCPServer } from "@databricks/langchainjs";

export function getMCPServers(): DatabricksMCPServer[] {
  return [
    // Formula 1 Genie Space
    DatabricksMCPServer.fromGenieSpace("01f1037ebc531bbdb27b875271b31bf4"),

    // Add more MCP servers here...
  ];
}
```

**Step 2:** Grant access in `databricks.yml`:
```yaml
resources:
  apps:
    agent_langchain_ts:
      resources:
        - name: 'f1_genie_space'
          genie_space:
            name: 'Formula 1 Race Analytics'
            space_id: '01f1037ebc531bbdb27b875271b31bf4'
            permission: 'CAN_RUN'
```

**Step 3:** Deploy with `databricks bundle deploy` (see **deploy** skill)

## Resource Type Examples

See the `examples/` directory for complete YAML snippets:

| File | Resource Type | When to Use |
|------|--------------|-------------|
| `uc-function.yaml` | Unity Catalog function | UC functions via MCP |
| `uc-connection.yaml` | UC connection | External MCP servers |
| `vector-search.yaml` | Vector search index | RAG applications |
| `sql-warehouse.yaml` | SQL warehouse | SQL execution |
| `serving-endpoint.yaml` | Model serving endpoint | Model inference |
| `genie-space.yaml` | Genie space | Natural language data |
| `experiment.yaml` | MLflow experiment | Tracing (already configured) |
| `custom-mcp-server.md` | Custom MCP apps | Apps starting with `mcp-*` |

## Custom MCP Servers (Databricks Apps)

Apps are **not yet supported** as resource dependencies in `databricks.yml`. Manual permission grant required:

**Step 1:** Get your agent app's service principal:
```bash
databricks apps get <your-agent-app-name> --output json | jq -r '.service_principal_name'
```

**Step 2:** Grant permission on the MCP server app:
```bash
databricks apps update-permissions <mcp-server-app-name> \
  --service-principal <agent-app-service-principal> \
  --permission-level CAN_USE
```

See `examples/custom-mcp-server.md` for detailed steps.

## TypeScript-Specific Patterns

### Adding Multiple MCP Servers

Edit `src/mcp-servers.ts`:
```typescript
export function getMCPServers(): DatabricksMCPServer[] {
  const servers: DatabricksMCPServer[] = [];

  // Genie Space
  servers.push(
    DatabricksMCPServer.fromGenieSpace("01f1037ebc531bbdb27b875271b31bf4")
  );

  // SQL MCP
  servers.push(
    new DatabricksMCPServer({
      name: "dbsql",
      path: "/api/2.0/mcp/sql",
    })
  );

  // UC Functions
  servers.push(
    DatabricksMCPServer.fromUCFunction("main", "default")
  );

  // Vector Search
  servers.push(
    DatabricksMCPServer.fromVectorSearch("main", "default", "my_index")
  );

  return servers;
}
```

### LangChain Agent Pattern

The agent uses standard LangGraph `createReactAgent` API:
```typescript
// In src/agent.ts - uses standard LangGraph pattern
import { createReactAgent } from "@langchain/langgraph/prebuilt";

export async function createAgent(config: AgentConfig = {}) {
  // Load tools (basic + MCP if configured)
  const tools = await getAllTools(config.mcpServers);

  // Create agent using standard LangGraph API
  // Automatically handles tool execution, reasoning, and state management
  const agent = createReactAgent({
    llm: model,
    tools,
  });

  return new StandardAgent(agent, systemPrompt);
}
```

## MCP Tool Types

| Tool Type | Use Case | MCP URL Pattern |
|-----------|----------|-----------------|
| **Databricks SQL** | Execute SQL queries on Unity Catalog tables | `/api/2.0/mcp/sql` |
| **UC Functions** | Call Unity Catalog functions as tools | `/api/2.0/mcp/functions/{catalog}/{schema}` |
| **Vector Search** | Semantic search over embeddings for RAG | `/api/2.0/mcp/vector-search/{catalog}/{schema}/{index}` |
| **Genie Spaces** | Natural language data queries | `/api/2.0/mcp/genie/{space_id}` |

## Troubleshooting

See [Troubleshooting Guide](../_shared/TROUBLESHOOTING.md) for common issues.

**Quick tips:**
- Permission errors: Check `databricks.yml` and redeploy
- Tool not found: Verify `src/mcp-servers.ts` and restart server
- MCP issues: See `mcp-known-issues.md` and `mcp-best-practices.md` in this directory

## Additional Resources

- **`mcp-known-issues.md`** - Known MCP integration issues and status
- **`mcp-best-practices.md`** - Correct implementation patterns for MCP tools
- **`examples/`** - YAML configuration examples for all resource types

## Important Notes

- **MLflow experiment**: Already configured in template, no action needed
- **Multiple resources**: Add multiple entries under `resources:` list
- **Permission types vary**: Each resource type has specific permission values
- **Deploy after changes**: Run `databricks bundle deploy` after modifying `databricks.yml`
- **Genie spaces**: Use `CAN_RUN` permission for Genie spaces
- **Service principal**: Deployed apps run as service principals and need explicit resource grants