# 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**](https://docs.agenticflow.ai/ai-agents/03-agents) - Understanding all 11 configuration tabs
* [**Model Selection**](https://docs.agenticflow.ai/ai-agents/model-selection) - Choosing the right AI model for tool use
* [**Workflow Tools**](https://docs.agenticflow.ai/ai-agents/workflows) - Configure workflows as agent tools
* [**Knowledge Base**](https://docs.agenticflow.ai/ai-agents/knowledge) - 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! 🚀