# MCP Tools Configuration

## 🌐 **What is MCP?**

**MCP (Model Context Protocol)** is like a universal connector that lets your AI agent access external tools and data—think of it as giving your agent superpowers to interact with the real world.

### **What MCP Does for Your Agent**

Instead of just chatting, your agent can now:

* 📁 **Read and write files** in your project folders
* 🗄️ **Query databases** to fetch business data
* 📧 **Send emails** through Gmail or Outlook
* 💬 **Post messages** to Slack or Teams
* 🎫 **Create tickets** in Jira or Zendesk
* 🔍 **Search code** in GitHub repositories
* 📊 **Fetch analytics** from your business tools
* 🛒 **Access CRM data** from Salesforce or HubSpot
* ⚡ **And 300+ more integrations**

### **Why Use MCP?**

**Before MCP:**

* Agents could only chat and answer questions
* No access to your files, databases, or business tools
* Limited to what's in their training data

**With MCP:**

* Agents take real actions in your systems
* Access live data from your business applications
* Automate workflows across multiple tools
* Work with your actual project files and data

***

## 🔧 **How MCP Works (Simple Explanation)**

Think of MCP like adding apps to your smartphone:

1. **MCP Servers** = App Store apps (Gmail, Slack, GitHub, etc.)
2. **MCP Connections** = Installing and logging into apps
3. **MCP Tools** = Features within each app (send email, post message, search code)
4. **Your Agent** = The user who can now use these apps

**Example Workflow:**

1. You set up a connection to Gmail (like logging into Gmail on your phone)
2. Your agent can now access Gmail tools (send email, read inbox, etc.)
3. When a user asks "Send this to my team", the agent uses the Gmail tool
4. The email gets sent—just like you would do manually

***

## 🚀 **Setting Up MCP Tools (2-Step Process)**

### **Step 1: Create MCP Connections** (One-Time Setup)

Before your agent can use MCP tools, you need to set up connections to the services you want to use.

#### **Where to Set Up Connections**

1. Go to your **Project Settings**
2. Click on **Connections** or **Integrations**
3. Click **"Add Connection"**
4. Select **"MCP Client"**

#### **What You'll Configure**

**1. Name Your Connection**

* Give it a clear, descriptive name
* Example: "GitHub Code Access", "Gmail for Support", "Analytics Database"

**2. Enter Server URL**

* This is the address of the MCP server
* Your provider or IT team will give you this URL
* Example: `https://mcp.github.com/v1`

**3. Choose Transport Type**

* **Streamable HTTP**: Modern standard, recommended for all new connections
* **SSE (Server-Sent Events)**: Legacy method, being deprecated
* If unsure, use **Streamable HTTP**

**4. Set Up Authentication**

You have two options:

**Option A: No Authentication**

* For internal tools or public services
* Just click "Save" and you're done

**Option B: OAuth (Secure Login)**

* For services like Gmail, GitHub, Slack
* Click **"Initialize OAuth"**
* You'll be redirected to login (like "Sign in with Google")
* Approve the permissions
* AgenticFlow saves your login securely
* Tokens refresh automatically—no need to re-login

**5. Test Connection**

* Click **"Test Connection"**
* You'll see a list of available tools
* Green checkmark = Connection works!
* Red error = Check your URL or authentication

#### **Example: Setting Up Gmail**

```
Name: Gmail for Customer Support
URL: https://mcp.gmail.com/v1
Transport: Streamable HTTP
Authentication: OAuth
  → Click "Initialize OAuth"
  → Login with your Google account
  → Approve email permissions
  → Done! ✓
```

### **Step 2: Add MCP Tools to Your Agent**

Now that connections are set up, configure which ones your agent can use.

#### **In Agent Builder → Tab 5: MCP Tools**

**1. Click "Add MCP Client"**

* Select from your configured connections
* You'll see all available tools from that service

**2. Configure Tool Behavior**

**Run Behavior:** How the agent uses tools

* **Auto Run** (Recommended for most cases)
  * Agent automatically uses tools when needed
  * Best for: File reading, data queries, searches
  * Example: "Show me the latest sales data" → Agent queries database automatically
* **Request Confirmation** (For sensitive actions)
  * Agent asks user before using tool
  * Best for: Sending emails, creating tickets, deleting files
  * Example: "Send email to client" → Agent asks "Should I send this email?" → User confirms

**Timeout:** How long to wait for tool response

* Default: 150 seconds (2.5 minutes)
* Increase for slow operations (large file processing, complex queries)
* Decrease for quick operations (simple API calls)

**3. Select Specific Tools (Optional)**

By default, your agent can use **all tools** from the connection. You can customize:

**Allow All Tools:**

* Leave tool selection empty
* Agent can use any tool from this connection
* Good when you trust all capabilities

**Choose Specific Tools:**

* Toggle which tools the agent can use
* Example: For GitHub, allow "search code" and "read file" but not "delete repository"
* Prevents accidental destructive actions

**4. Add Usage Instructions (Optional)**

Tell your agent when and how to use these tools:

**Example for File System:**

```
Use these tools when users ask to read, write, or organize files in their project.
Always check if a file exists before trying to read it.
Ask for confirmation before deleting any files.
```

**Example for CRM:**

```
Search customer records when users ask about account details or contact information.
Always create new leads when a potential customer is mentioned.
Update contact details when users provide new information.
```

**Example for Email:**

```
Send emails only when explicitly requested.
Always show the draft to the user before sending.
Use professional tone in all email communications.
```

***

## 🎯 **Common MCP Tool Setups**

### **Setup 1: Customer Support Agent**

**Goal:** Agent handles support tickets and emails

**MCP Connections Needed:**

1. **Gmail** - Send and read customer emails
2. **Zendesk** - Create and update support tickets
3. **Knowledge Base** - Search help documentation

**Agent Configuration:**

```
MCP Client: Gmail
  Run Behavior: Request Confirmation
  Timeout: 60 seconds
  Tools: Send email, read inbox, search messages
  Instructions: "Always show email drafts before sending"

MCP Client: Zendesk
  Run Behavior: Auto Run
  Timeout: 90 seconds
  Tools: Create ticket, update ticket, search tickets
  Instructions: "Create tickets for all customer issues"

MCP Client: Knowledge Base
  Run Behavior: Auto Run
  Timeout: 30 seconds
  Tools: Search articles, get article content
  Instructions: "Search help docs before escalating to human"
```

### **Setup 2: Development Assistant Agent**

**Goal:** Agent helps with coding and project management

**MCP Connections Needed:**

1. **GitHub** - Access code repositories
2. **Jira** - Manage development tasks
3. **File System** - Read/write project files

**Agent Configuration:**

```
MCP Client: GitHub
  Run Behavior: Auto Run
  Timeout: 120 seconds
  Tools: Search code, read file, list repositories
  Instructions: "Help find code examples and explain implementations"

MCP Client: Jira
  Run Behavior: Request Confirmation
  Timeout: 60 seconds
  Tools: Create issue, update issue, search issues
  Instructions: "Create tickets for bugs, ask before updating existing tickets"

MCP Client: Project Files
  Run Behavior: Auto Run
  Timeout: 45 seconds
  Tools: Read file, list directory (delete disabled)
  Instructions: "Read project files when analyzing code structure"
```

### **Setup 3: Sales & Analytics Agent**

**Goal:** Agent provides business insights and manages leads

**MCP Connections Needed:**

1. **Salesforce** - CRM data and lead management
2. **Analytics Database** - Business metrics
3. **Slack** - Team notifications

**Agent Configuration:**

```
MCP Client: Salesforce CRM
  Run Behavior: Request Confirmation
  Timeout: 90 seconds
  Tools: Search contacts, create lead, view opportunities
  Instructions: "Look up customer details, create leads for new prospects"

MCP Client: Analytics Database
  Run Behavior: Auto Run
  Timeout: 120 seconds
  Tools: Execute query, list tables
  Instructions: "Query sales metrics, user statistics, and performance data"

MCP Client: Slack Notifications
  Run Behavior: Auto Run
  Timeout: 30 seconds
  Tools: Post message, send to channel
  Instructions: "Notify #sales channel for high-value leads"
```

***

## 🛡️ **Security & Permissions**

### **Authentication Security**

**OAuth (Recommended):**

* Most secure method for cloud services
* You login once, AgenticFlow handles the rest
* Tokens stored encrypted
* Auto-refreshes—no re-authentication needed
* Can revoke access anytime from service settings

**No Authentication:**

* Only use for internal/private tools
* Good for tools on your private network
* Not recommended for internet-facing services

### **Tool Permissions Best Practices**

**Grant Only What's Needed:**

* ✅ **DO**: Enable "read file" for code review agents
* ❌ **DON'T**: Enable "delete file" unless absolutely necessary

**Use Request Confirmation for:**

* Sending emails or messages
* Creating/updating database records
* Deleting any data
* Making purchases or financial transactions
* Publishing content publicly

**Use Auto Run for:**

* Reading files or data
* Searching and querying
* Fetching information
* Generating reports
* Non-destructive operations

### **Monitoring & Safety**

**What AgenticFlow Tracks:**

* Every tool your agent uses
* When tools are called and by which user
* Success or failure of each tool call
* Time taken for each operation

**Review Agent Logs:**

* Check which tools are being used most
* Identify failed tool calls
* Monitor for unexpected behavior
* Audit sensitive operations

***

## 🔍 **Troubleshooting Common Issues**

### **Issue: "Authentication Failed"**

**What it means:** Agent can't connect to the MCP server

**How to fix:**

1. Go to **Connection Settings** → Find the MCP connection
2. Check if status shows "Not Authenticated"
3. For OAuth: Click **"Re-authorize"** and login again
4. For No Auth: Verify the server URL is correct
5. Click **"Test Connection"** to verify

### **Issue: "Tool Not Found"**

**What it means:** Agent tries to use a tool that's not available

**How to fix:**

1. Go to **Agent Builder** → **Tab 5: MCP Tools**
2. Verify the MCP client is added to your agent
3. Check the tool name is spelled correctly
4. In tool selection, make sure the tool is **enabled** (toggled on)
5. Test the connection to see available tools

### **Issue: "Timeout Error"**

**What it means:** Tool took too long to respond

**How to fix:**

1. Go to **Agent Builder** → **Tab 5: MCP Tools**
2. Find the MCP client configuration
3. Increase the **Timeout** value (try 200-300 seconds)
4. If still failing, contact your MCP server administrator
5. Consider if the operation is too complex (query too large, file too big)

### **Issue: "Permission Denied"**

**What it means:** Agent doesn't have permission for this tool

**How to fix:**

1. Check if tool is enabled in agent configuration
2. For OAuth: Re-authorize with correct permissions/scopes
3. Verify your user account has permission in the external service
4. Check if IP whitelisting is needed for your MCP server

### **Issue: "Agent Doesn't Use Tools"**

**What it means:** Agent answers questions but doesn't use MCP tools

**How to fix:**

1. **Add instructions** in MCP tool description
2. **Update system prompt** to mention when to use tools
3. **Test directly**: Ask "Can you read the file X?" (be explicit)
4. **Check model selection**: Some models are better at tool use (Claude, GPT-4)
5. **Verify tools are enabled** in agent configuration

***

## 📊 **Monitoring Tool Usage**

### **View Agent Activity**

**In Agent Dashboard:**

* See which tools were called in each conversation
* View success/failure rates
* Check average response times
* Monitor token usage

**In Connection Settings:**

* See when OAuth tokens expire
* Check connection health status
* View last successful connection
* Test tools on-demand

### **Understanding Tool Performance**

**Good Performance:**

* Tool calls succeed > 95% of time
* Response time < 5 seconds for most operations
* OAuth tokens refresh automatically
* No authentication errors

**Needs Attention:**

* Success rate < 90%
* Frequent timeout errors
* Repeated authentication failures
* Users complaining about slow responses

**Optimization Tips:**

* Increase timeout for slow operations
* Use caching when possible
* Limit number of tools per agent (5-10 is ideal)
* Remove unused MCP connections
* Monitor during peak usage times

***

## ✅ **Best Practices Checklist**

### **Before Deployment**

* [ ] **Test each MCP connection** - Click "Test Connection" and verify tools appear
* [ ] **Authenticate OAuth services** - Complete login flow and verify "Authorized" status
* [ ] **Configure timeouts appropriately** - 30s for fast operations, 120s+ for slow
* [ ] **Set run behavior** - Auto Run for safe operations, Request Confirmation for sensitive
* [ ] **Add usage instructions** - Tell agent when and how to use each tool
* [ ] **Test in chat** - Ask agent to use each tool and verify it works
* [ ] **Review permissions** - Disable dangerous tools (delete, publish, etc.)
* [ ] **Document setup** - Note which connections are used and why

### **After Deployment**

* [ ] **Monitor agent logs** - Check tool usage weekly
* [ ] **Review tool performance** - Look for errors or slow operations
* [ ] **Update OAuth tokens** - Re-authorize if seeing auth errors
* [ ] **Gather user feedback** - Ask if tools are working as expected
* [ ] **Optimize configuration** - Remove unused tools, adjust timeouts
* [ ] **Security audit** - Review permissions quarterly
* [ ] **Update instructions** - Refine based on actual usage patterns

***

## 🎓 **Tips for Success**

### **Start Simple**

* Begin with 1-2 MCP connections
* Test thoroughly before adding more
* Add tools gradually based on actual needs
* Don't overwhelm your agent with too many options

### **Name Things Clearly**

* Use descriptive connection names: "Gmail for Support" not "Connection 1"
* Write clear usage instructions
* Document what each tool does
* Make it easy for future you to understand

### **Test Before Going Live**

* Use Chat Playground to test each tool
* Try edge cases (empty results, errors, timeouts)
* Verify confirmations work as expected
* Check that errors are handled gracefully

### **Guide Your Agent**

* Add instructions for when to use tools
* Include examples in system prompt
* Mention tools in agent knowledge base
* Be specific about use cases

### **Monitor and Improve**

* Check logs regularly
* Look for patterns in tool usage
* Identify and fix common errors
* Adjust based on user feedback

***

## 🔗 **Related Documentation**

* [**Agent Configuration Overview**](/ai-agents/03-agents.md) - Understanding all 11 configuration tabs
* [**Model Selection**](/ai-agents/model-selection.md) - Choosing the right AI model for tool use
* [**Workflow Tools**](/ai-agents/workflows.md) - Configure workflows as agent tools
* [**Knowledge Base**](/ai-agents/knowledge.md) - Combining MCP tools with knowledge

***

## 📚 **Learn More About MCP**

**What is MCP?**

* Visit [modelcontextprotocol.io](https://modelcontextprotocol.io) for the official guide
* Universal standard for AI tool integrations
* Created by Anthropic, adopted industry-wide
* Open-source and extensible

**Finding MCP Servers:**

* Browse official server directory
* Search npm for `@modelcontextprotocol/*` packages
* Check your service provider's documentation
* Many popular tools have official MCP servers

**Custom Integrations:**

* Contact AgenticFlow support for custom MCP server setup
* Work with your IT team to deploy internal MCP servers
* Request new integrations from the AgenticFlow team

***

**Need Help?**

* **In-App Support**: Click the help icon in Agent Builder
* **Community**: Ask in AgenticFlow community forums
* **Support Team**: Contact <support@agenticflow.ai>

Your agent's MCP tools transform it from a chatbot into a powerful automation assistant—configure thoughtfully, test thoroughly, and watch your agent handle real work! 🚀


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agenticflow.ai/ai-agents/mcp-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.