Tool Integration and MCP Configuration

This guide explains how to configure and use AI tools in PromptOwl , including built-in tools and external MCP (Model Context Protocol) servers.

Table of Contents

1. Tools Overview
2. Accessing Tool Configuration
3. Built-in Tools
4. Configuring Tool API Keys
5. MCP Server Integration
6. Connecting Tools to Prompts
7. How Tools Work in Chat
8. Tool Permissions and Security
9. Best Practices
10. 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

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:

Built-in Tools

PromptOwl includes four built-in tools ready to use.

Calculator

Performs mathematical calculations.

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.

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.

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.

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 
2. Create an account
3. Navigate to API Keys
4. Copy your API key

Brave Search:

1. Visit 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

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:

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

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

Enterprise Controls

Administrators can control tool availability:

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

Related Guides

• Editing and Maintaining Prompts
• Understanding Agents and RAG
• Enterprise Setup and White-Label