firecrawl · PratikKhaire · Dec 12, 2025
diff --git a/.github/ISSUE_TEMPLATE/agent-tool-routing.md b/.github/ISSUE_TEMPLATE/agent-tool-routing.md
@@ -0,0 +1,127 @@
+---
+name: Agent Tool Routing Issue
+about: Report issues with agents incorrectly executing MCP tools as bash commands
+title: '[Agent Routing] '
+labels: 'agent-issue, client-side'
+assignees: ''
+---
+
+## ⚠️ Important Note
+
+This issue appears to be related to how AI agent clients (Claude Desktop, Cursor, etc.) route MCP tool calls. This is typically a **client-side configuration issue**, not a bug in the Firecrawl MCP Server.
+
+**Before filing this issue**, please:
+1. Review our [Agent Configuration Guide](../../docs/AGENT_CONFIGURATION.md)
+2. Try the solutions in [Troubleshooting Guide](../../docs/TROUBLESHOOTING.md  
+3. Consider reporting to your AI client support if the issue persists
+
+---
+
+## Problem Description
+
+**Symptom**: Agent attempts to execute Firecrawl MCP tool as a bash command
+
+**Error Message**:
+```
+/bin/bash: line 1: mcp__firecrawl__firecrawl_scrape: command not found
+```
+
+## Environment
+
+**AI Client** (check one):
+- [ ] Claude Desktop
+- [ ] Cursor
+- [ ] VS Code with Cline/Continue
+- [ ] Windsurf
+- [ ] Other (please specify): ___________
+
+**Client Version**: (e.g., Claude Desktop 1.2.3, Cursor 0.48.6)
+
+**Operating System**:
+- [ ] macOS
+- [ ] Windows
+- [ ] Linux (which distro): ___________
+- [ ] Cloud VM (which provider): ___________
+
+**Deployment Type**:
+- [ ] Local (stdio)
+- [ ] HTTP/HTTPS
+- [ ] SSE (Server-Sent Events)
+
+## MCP Server Configuration
+
+**Firecrawl MCP Version**: (run `npx -y firecrawl-mcp --version`)
+
+**Configuration** (sanitize your API key):
+```json
+{
+  "mcpServers": {
+    "firecrawl-mcp": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "<REDACTED>"
+      }
+    }
+  }
+}
+```
+
+## Steps to Reproduce
+
+1. Configure Firecrawl MCP Server in your AI client
+2. Verify direct tool calls work: "use firecrawl to scrape https://example.com"
+3. Create an agent that attempts to use Firecrawl tools
+4. Observe agent executing: `Bash(mcp__firecrawl__firecrawl_scrape '...')`
+
+## Expected Behavior
+
+Agent should invoke Firecrawl MCP tool through the MCP protocol, resulting in successful scraping.
+
+## Actual Behavior
+
+Agent wraps MCP tool call in `Bash()` execution, resulting in "command not found" error.
+
+## Verification Checklist
+
+- [ ] Direct MCP tool calls work (not through agent)
+- [ ] MCP server shows as "connected" in client settings
+- [ ] Tried latest version of Firecrawl MCP (`npm install -g firecrawl-mcp@latest`)
+- [ ] Reviewed [Agent Configuration Guide](../../docs/AGENT_CONFIGURATION.md)
+- [ ] Added `agentSupport: true` or `allowedForAgents: true` to configuration
+- [ ] Restarted AI client after configuration changes
+
+## Logs
+
+**MCP Server Logs** (if available):
+```
+[Paste MCP server logs here]
+```
+
+**Agent Error Output**:
+```
+[Paste full error message here]
+```
+
+## Additional Context
+
+Add any other context about the problem here. For example:
+- Does the issue occur with all Firecrawl tools or specific ones?
+- Does the issue occur with all agents or specific agent configurations?
+- Any custom agent system prompts being used?
+
+---
+
+## Next Steps
+
+Based on our investigation, this is likely a client-side issue. Please:
+
+1. **Try the configuration fixes** in our [Agent Configuration Guide](../../docs/AGENT_CONFIGURATION.md)
+2. **If issue persists**, report to your AI client's support:
+   - Claude Desktop: https://support.anthropic.com
+   - Cursor: https://forum.cursor.com
+   - VS Code: Your MCP client extension's issue tracker
+
+3. **Update this issue** with results from trying the recommended fixes
+
+We'll help troubleshoot and update our documentation based on your findings!
diff --git a/docs/AGENT_CONFIGURATION.md b/docs/AGENT_CONFIGURATION.md
@@ -0,0 +1,148 @@
+# Agent Configuration Guide
+
+This guide explains how to configure Firecrawl MCP Server for AI agent usage.
+
+##  Problem: Agent Tool Routing Issue
+
+When AI agents (vs direct chat) attempt to invoke Firecrawl MCP tools, they may incorrectly wrap the tool calls in `Bash()` execution, resulting in:
+
+```
+Error: /bin/bash: line 1: mcp__firecrawl__firecrawl_scrape: command not found
+```
+
+**Root Cause**: This is a client-side issue where agents misroute MCP tools to bash instead of the MCP protocol.
+
+## Solutions
+
+### 1. Claude Desktop Configuration
+
+Add `agentSupport` flag to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "firecrawl-mcp": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
+      },
+      "agentSupport": true
+    }
+  }
+}
+```
+
+### 2. Cursor Configuration (v0.48.6+)
+
+Add `allowedForAgents` to your MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "firecrawl-mcp": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
+      },
+      "allowedForAgents": true
+    }
+  }
+}
+```
+
+### 3. Google Cloud VM / Claude Code (HTTPS Mode)
+
+For Claude Code running on Google Cloud VM with HTTPS transport:
+
+```json
+{
+  "mcpServers": {
+    "firecrawl-mcp": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "YOUR_API_KEY",
+        "CLOUD_SERVICE": "true",
+        "HTTP_STREAMABLE_SERVER": "true"
+      },
+      "agentSupport": true,
+      "transportType": "httpStream"
+    }
+  }
+}
+```
+
+### 4. Agent System Prompt
+
+When creating custom agents, add explicit instructions:
+
+```
+SYSTEM PROMPT:
+"When you need to scrape web pages, use the firecrawl_scrape MCP tool.
+Do NOT execute it as a bash command.
+Call it as an MCP protocol tool with proper JSON arguments."
+
+Example correct invocation:
+{
+  "tool": "firecrawl_scrape",
+  "arguments": {
+    "url": "https://example.com",
+    "formats": ["markdown"]
+  }
+}
+```
+
+## Verification Steps
+
+1. **Check MCP Server Connection**
+   - Open your AI client settings
+   - Verify `firecrawl-mcp` shows as "connected" or "active"
+
+2. **Test Direct Invocation First**
+   ```
+   Direct chat: "Use firecrawl to scrape https://example.com"
+   Expected: Success ✅
+   ```
+
+3. **Test Agent Invocation**
+   - Create an agent with the configuration above
+   - Have the agent attempt to scrape a URL
+   - Expected: No bash error, successful scrape ✅
+
+## Troubleshooting
+
+### Agent still wraps tool in Bash()
+
+**Solution**: Update to latest MCP server version and client software:
+```bash
+npm install -g firecrawl-mcp@latest
+```
+
+### MCP server not showing in agent context
+
+**Solution**: Restart your AI client after configuration changes.
+
+### Permission denied errors
+
+**Solution**: Ensure API key is valid and has proper permissions:
+```bash
+# Test API key
+curl -X POST https://api.firecrawl.dev/v1/scrape \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}'
+```
+
+## Related Issues
+
+- See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for more detailed debugging
+- Report client-side agent issues to your AI client support (Claude/Cursor/etc)
+- Report MCP server bugs to: https://github.com/firecrawl/firecrawl-mcp-server/issues
+
+## Additional Resources
+
+- [MCP Protocol Specification](https://modelcontextprotocol.io)
+- [Claude Code Documentation](https://docs.anthropic.com/claude/docs/model-context-protocol)
+- [Cursor MCP Guide](https://docs.cursor.com/context/model-context-protocol)
diff --git a/docs/README_ADDITION.md b/docs/README_ADDITION.md
@@ -0,0 +1,94 @@
+# README Addition: Agent Configuration Section
+
+Add this section to the main README.md after the existing installation sections and before the "Configuration" section.
+
+---
+
+## Agent Configuration
+
+### Using Firecrawl MCP with AI Agents
+
+When using Firecrawl MCP tools with AI agents (as opposed to direct chat), you may need additional configuration to ensure proper tool routing.
+
+#### Known Issue: Agent Tool Routing
+
+**Symptom**: Agents may incorrectly execute MCP tools as bash commands, resulting in:
+```
+Error: /bin/bash: line 1: mcp__firecrawl__firecrawl_scrape: command not found
+```
+
+**Cause**: This is a client-side issue where AI agents wrap MCP tool calls in `Bash()` execution instead of routing through the MCP protocol.
+
+**Solution**: Add agent support flags to your configuration:
+
+**For Claude Desktop:**
+```json
+{
+  "mcpServers": {
+    "firecrawl-mcp": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
+      },
+      "agentSupport": true
+    }
+  }
+}
+```
+
+**For Cursor (v0.48.6+):**
+```json
+{
+  "mcpServers": {
+    "firecrawl-mcp": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "YOUR_API_KEY"
+      },
+      "allowedForAgents": true
+    }
+  }
+}
+```
+
+**For Google Cloud VM / HTTPS Deployment:**
+```json
+{
+  "mcpServers": {
+    "firecrawl-mcp": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "YOUR_API_KEY",
+        "CLOUD_SERVICE": "true",
+        "HTTP_STREAMABLE_SERVER": "true"
+      },
+      "agentSupport": true,
+      "transportType": "httpStream"
+    }
+  }
+}
+```
+
+#### Verification
+
+1. **Test Direct Invocation**:
+   ```
+   Chat: "use firecrawl to scrape https://example.com"
+   Expected: Success ✅
+   ```
+
+2. **Test Agent Invocation**:
+   - Create an agent with the above configuration
+   - Have the agent scrape a URL
+   - Expected: No bash error, successful scrape ✅
+
+#### More Information
+
+- 📚 [Agent Configuration Guide](./docs/AGENT_CONFIGURATION.md)
+- 🔧 [Troubleshooting Guide](./docs/TROUBLESHOOTING.md)
+- 🐛 [Report Agent Issues](https://github.com/firecrawl/firecrawl-mcp-server/issues/new?template=agent-tool-routing.md)
+
+---