# Tool Integration and MCP Configuration

This guide explains how to configure and use AI tools in [PromptOwl](https://promptowl.ai), including built-in tools and external MCP (Model Context Protocol) servers.

---

## Table of Contents

1. [Tools Overview](#tools-overview)
2. [Accessing Tool Configuration](#accessing-tool-configuration)
3. [Built-in Tools](#built-in-tools)
4. [Configuring Tool API Keys](#configuring-tool-api-keys)
5. [MCP Server Integration](#mcp-server-integration)
6. [Connecting Tools to Prompts](#connecting-tools-to-prompts)
7. [How Tools Work in Chat](#how-tools-work-in-chat)
8. [Tool Permissions and Security](#tool-permissions-and-security)
9. [Best Practices](#best-practices)
10. [Troubleshooting](#troubleshooting)

---

## Tools Overview

Tools extend your AI agent's capabilities beyond text generation. When tools are enabled, the AI can:

- **Perform calculations** using the calculator tool
- **Get current date/time** for time-sensitive queries
- **Search the web** using Serper or Brave search APIs
- **Execute custom actions** via MCP servers (e.g., database queries, API calls)

### How Tools Work

```
User asks question → AI analyzes if tool is needed →
AI calls appropriate tool → Tool returns result →
AI incorporates result into response
```

The AI automatically decides when to use tools based on the user's question. You don't need to explicitly request tool usage.

### Tool Types

| Type | Description | Examples |
|------|-------------|----------|
| **Built-in Tools** | Pre-configured tools included with PromptOwl | Calculator, Date/Time |
| **API Tools** | Built-in tools requiring API keys | Serper Search, Brave Search |
| **MCP Server Tools** | External tools from custom MCP servers | Custom integrations, databases |

---

## Accessing Tool Configuration

### Navigation

1. Click **Tools** in the left sidebar
2. View the Tools Configuration page


### Configuration Page Layout

The Tools page has two main sections:

| Section | Purpose |
|---------|---------|
| **Pre-defined Custom Tools** | Built-in tools you can enable/disable |
| **MCP Servers** | External tool servers you connect |


---

## Built-in Tools

PromptOwl includes four built-in tools ready to use.

### Calculator

Performs mathematical calculations.

| Setting | Value |
|---------|-------|
| **Default Status** | Enabled |
| **Configuration Required** | None |
| **Use Cases** | Math problems, unit conversions, percentages |

**Example Queries:**
- "What's 15% of 847?"
- "Calculate the compound interest on $10,000 at 5% for 3 years"
- "Convert 100 kilometers to miles"

### Date and Time

Returns current date and time in various formats.

| Setting | Value |
|---------|-------|
| **Default Status** | Enabled |
| **Configuration Required** | None |
| **Formats** | ISO, date-only, time-only, local |

**Example Queries:**
- "What day is it today?"
- "How many days until December 31st?"
- "What time is it in ISO format?"

### Serper Search

Web search powered by Google Serper API.

| Setting | Value |
|---------|-------|
| **Default Status** | Disabled (requires API key) |
| **Configuration Required** | Serper API Key |
| **Options** | Region, language, max results, safe search |

**Example Queries:**
- "Search for the latest news about renewable energy"
- "Find information about Python 3.12 features"

### Brave Search

Web search powered by Brave Search API.

| Setting | Value |
|---------|-------|
| **Default Status** | Disabled (requires API key) |
| **Configuration Required** | Brave API Key |
| **Options** | Region, language, max results, safe search |

**Example Queries:**
- "Search for best practices in API design"
- "Find recent research on machine learning"


---

## Configuring Tool API Keys

Some tools require API keys to function. Here's how to configure them.

### Getting API Keys

**Serper Search:**
1. Visit [serper.dev](https://serper.dev)
2. Create an account
3. Navigate to API Keys
4. Copy your API key

**Brave Search:**
1. Visit [brave.com/search/api](https://brave.com/search/api)
2. Sign up for API access
3. Generate an API key
4. Copy your API key

### Adding API Keys

1. Find the tool card (e.g., Serper Search)
2. Click the **expand arrow** to show configuration
3. Enter your API key in the password field
4. Click **Save**


### Tool Status Indicators

| Status | Meaning | Badge Color |
|--------|---------|-------------|
| **Ready** | Tool is enabled and configured | Green |
| **Needs Config** | Tool enabled but missing API key | Yellow |
| **Disabled** | Tool is turned off | Gray |
| **Error** | Configuration issue | Red |

### Enabling/Disabling Tools

1. Find the tool card
2. Click the **toggle switch**
3. Tool status updates immediately

> **Note**: Tools with "Needs Config" status won't work until you add the required API key.

---

## MCP Server Integration

MCP (Model Context Protocol) allows you to connect external tool servers to PromptOwl.

### What is MCP?

MCP is a protocol that allows AI systems to use external tools. MCP servers can provide:

- Database query capabilities
- Custom API integrations
- Specialized business logic
- Third-party service connections

### Adding an MCP Server

1. Scroll to the **MCP Servers** section
2. Click **Add MCP Server**
3. Fill in the server details:

| Field | Description | Example |
|-------|-------------|---------|
| **Server Name** | Friendly name for the server | "Company Database" |
| **Server URL** | Endpoint where MCP server runs | `http://localhost:3001/mcp` |
| **Authentication** | Auth method (currently no-auth supported) | No Authentication |

4. Click **Save**


### Managing MCP Servers

**View Server Details:**
- Server cards show name, URL, creation date
- Status dot indicates enabled (green) or disabled (gray)

**Enable/Disable Server:**
- Click the toggle switch on the server card
- Disabled servers won't provide tools to prompts

**Edit Server:**
- Click the **pencil icon** on the server card
- Update name, URL, or authentication
- Click **Save**

**Delete Server:**
- Click the **trash icon** on the server card
- Confirm deletion in the dialog


### MCP Tool Discovery

When you add an MCP server, PromptOwl automatically:

1. Connects to the server URL
2. Discovers available tools
3. Makes tools available for prompt selection
4. Shows tools with "MCP" badge in tool selector

> **Timeout**: Tool discovery has a 30-second timeout. Ensure your MCP server responds quickly.

---

## Connecting Tools to Prompts

Tools are connected at the prompt level, giving you control over which prompts can use which tools.

### Adding Tools to a Prompt

1. Open a prompt for editing
2. Find the **Tools** section in the prompt editor
3. Click **Add Tool** (or the "+" button if tools exist)
4. Select tools from the available list
5. Click **Save**


### Tool Selection Interface

**Available Tools Section:**
- Shows all enabled built-in tools
- Shows all tools from enabled MCP servers
- MCP tools display server name below tool name
- Toggle to select/deselect tools

**Missing Tools Section:**
- Shows previously selected tools no longer available
- Grayed out with warning indicator
- Occurs when tool or server was disabled

### Visual Indicators

| Indicator | Meaning |
|-----------|---------|
| **Green pill** | Tool is connected and available |
| **MCP badge** | Tool comes from an MCP server |
| **Gray pill** | Tool was removed or disabled |


---

## How Tools Work in Chat

When chatting with a tool-enabled prompt, the AI automatically uses tools when appropriate.

### Tool Execution Flow

1. **User sends message** with a question
2. **AI analyzes** if any connected tools would help
3. **AI calls tool** with appropriate parameters
4. **Tool executes** and returns results
5. **AI processes** results and generates response
6. **User sees** final answer incorporating tool data

### Example Interaction

**User**: "What's the current stock price of Apple and calculate what a 10% gain would be?"

**AI Process:**
1. Recognizes need for web search (current data)
2. Calls Serper Search for "Apple stock price"
3. Gets result: $185.50
4. Calls Calculator for 185.50 * 1.10
5. Gets result: $204.05
6. Responds: "Apple's current stock price is $185.50. A 10% gain would bring it to $204.05."

### Tool Usage is Automatic

- You don't need to tell the AI to use tools
- The AI decides based on the question
- Multiple tools can be called in one response
- Tool calls happen in the background

### When Tools Are Not Used

The AI won't use tools when:
- The question can be answered from training data
- No relevant tools are connected
- The tool feature is disabled for the enterprise

---

## Tool Permissions and Security

### User-Level Isolation

- Each user has their own tool configurations
- API keys are stored per-user (encrypted)
- MCP servers are registered per-user
- Tool selections on prompts are user-specific

### API Key Security

| Security Measure | Description |
|-----------------|-------------|
| **Encryption** | API keys encrypted before storage |
| **Hidden Display** | Keys never shown after saving |
| **User Isolation** | Keys tied to specific user account |

### Enterprise Controls

Administrators can control tool availability:

| Control | Description |
|---------|-------------|
| **Feature Flag** | Enable/disable tools for entire enterprise |
| **MCP Panel** | Enable/disable MCP server configuration per client |

> **Note**: Tools can be enabled platform-wide by your administrator. Contact support if tools are not visible.

---

## Best Practices

### Tool Selection

**Do:**
- Enable only the tools your prompts actually need
- Use specific search tools for accurate results
- Test tools with sample queries before production use

**Don't:**
- Enable all tools on every prompt
- Share API keys between users
- Rely solely on web search for critical data

### MCP Server Setup

**Do:**
- Use descriptive server names
- Test server connectivity before adding
- Monitor server uptime and response times
- Document what tools each server provides

**Don't:**
- Add untrusted MCP servers
- Forget to update server URLs if they change
- Leave unused servers enabled

### Security Guidelines

1. **Rotate API keys** periodically
2. **Use separate keys** for test and production
3. **Review tool usage** in analytics
4. **Limit MCP server access** to necessary personnel

---

## Troubleshooting

### Tool Not Appearing in Selection

1. Check tool is **enabled** in Tools Configuration
2. Verify API key is configured (for API tools)
3. Confirm MCP server is **enabled** (for MCP tools)
4. Refresh the page and try again

### Tool Returns Errors

1. **API Tools**: Verify API key is valid and has quota
2. **MCP Tools**: Check server is running and accessible
3. **Calculator**: Ensure expression is valid math
4. **Search**: Try different search terms

### MCP Server Won't Connect

1. Verify server URL is correct and accessible
2. Check server is running and responding
3. Ensure no firewall blocking the connection
4. Review server logs for errors
5. Test URL directly in browser or curl

### Tool Results Not Used by AI

1. Confirm tool is connected to the prompt
2. Check question is relevant to tool capability
3. Try rephrasing the question
4. Verify tool returned valid results (check logs)

### "Needs Config" Status Won't Clear

1. Expand the tool configuration
2. Verify all required fields are filled
3. Check password meets requirements:
   - At least 8 characters
   - No spaces
   - Only alphanumeric, underscore, hyphen, period
4. Click **Save** after entering configuration

---

## Quick Reference

### Tool Configuration Checklist

**Basic Setup:**
- [ ] Calculator enabled (default)
- [ ] Date/Time enabled (default)
- [ ] Search tool API key added (if needed)
- [ ] MCP servers registered (if using)

**Per-Prompt:**
- [ ] Relevant tools selected
- [ ] Tools tested with sample queries
- [ ] Missing tools resolved

### Default Tool States

| Tool | Default | Requires Config |
|------|---------|-----------------|
| Calculator | Enabled | No |
| Date/Time | Enabled | No |
| Serper Search | Disabled | Yes (API key) |
| Brave Search | Disabled | Yes (API key) |
| MCP Tools | Disabled | Yes (server URL) |

---

## Related Guides

- [Editing and Maintaining Prompts](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/editing-maintaining-prompts)
- [Understanding Agents and RAG](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/understanding-agents-rag)
- [Enterprise Setup and White-Label](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/enterprise-setup-white-label)