MCP Server Integration
Connect your AI agents to external tools and services using the Model Context Protocol (MCP) - an open standard that enables seamless integration between AI systems and your existing infrastructure.
What is MCP?
The Model Context Protocol (MCP) is an open protocol developed by Anthropic that standardizes how AI applications communicate with external tools, data sources, and services. Think of it as a universal adapter that lets your AI agent interact with any system that speaks the MCP language.
Getting Started
Quick Start
- Navigate to Agent Studio → Select your agent → MCP Servers tab
- Click Add Server
- Enter the server details
- Click Test Connection to verify connectivity
- Review the available tools, then click Save Server
Your agent can now use the tools provided by your MCP server!
Configuration Reference
Essential Settings
These are the core settings required to connect to an MCP server.
Display Name
A friendly name to identify this server in your dashboard.
Example: "Customer Database" or "Logistics API"Base URL
The root URL of your MCP server.
Example: https://mcp.yourcompany.comNote: Must be a valid URL with http:// or https:// protocol. HTTPS is strongly recommended for production.
Connection Type
Choose how your agent communicates with the MCP server:
| Type | Description | When to Use |
|---|---|---|
| Streamable HTTP (Recommended) | Modern HTTP-based transport with streaming support | Default choice for most integrations |
| SSE (Legacy) | Server-Sent Events transport | Only if your MCP server doesn't support HTTP transport |
Endpoint Path
The path on the server where MCP requests are sent.
| Connection Type | Default Path |
|---|---|
| Streamable HTTP | /mcp |
| SSE | /sse |
Tip: Most MCP servers use the default paths. Only change this if your server uses a custom endpoint.
API Key / Secret Token
Authentication token for your MCP server (if required).
Example: sk-xxxxxxxxxxxxxxxxxxxxSecurity: Tokens are encrypted at rest and never displayed in the UI after saving. To update a configuration without changing the token, simply leave this field empty.
Advanced Settings
Fine-tune your integration with these optional settings.
Forward User Context
When enabled, Foldspace automatically includes the current user's identity in requests to your MCP server via the X-Foldspace-User-Id header.
| Setting | Behavior |
|---|---|
| Enabled | User's identify ID is sent with every MCP request |
| Disabled | No user context is forwarded (default) |
Use this when:
- Your MCP server needs to personalize responses per user
- You want to implement user-level access controls on your server
- You need to audit which user triggered which action
Example Header:
X-Foldspace-User-Id: user_abc123
X-Foldspace-Subscription-Id: sub_xyz789Custom Headers
Add static headers to every request sent to your MCP server.
| Use Case | Header Example |
|---|---|
| API Versioning | X-API-Version: 2024-01 |
| Routing | X-Environment: production |
Testing Your Integration
Before saving your configuration, always test the connection to ensure everything works correctly.
Test Connection
The Test Connection button performs a full MCP initialization handshake with your server:
| Result | Meaning |
|---|---|
| ✅ Success | Server is reachable and responds correctly to MCP protocol |
| ❌ Failed | Connection issue — check the error message for details |
Common Error Messages:
| Error | Cause | Solution |
|---|---|---|
| Connection refused | Server not running or wrong URL | Verify server is running and URL is correct |
| Connection timeout | Network issue or firewall blocking | Check network access and firewall rules |
| 401 Unauthorized | Invalid or missing API key | Verify your API key is correct |
| 404 Not Found | Wrong endpoint path | Check the endpoint path configuration |
| Protocol error | Server doesn't speak MCP | Ensure server implements MCP protocol correctly |
View Available Tools
After a successful connection test, click View Available Tools to see what capabilities your MCP server provides.
Each tool displays:
- Name — The identifier your agent uses to invoke the tool
- Description — What the tool does (shown to the AI)
- Input Schema — The parameters the tool accepts
Tip: Review the tool list to confirm you've connected to the correct server and the expected tools are available.
Limits & Quotas
| Resource | Limit |
|---|---|
| MCP servers per agent | 20 |
| Display name | Must be unique per agent |
| Base URL | Valid HTTP/HTTPS URL |
| custom headers | Recommended max 10 |
Troubleshooting
My agent isn't using the MCP tools
- Verify the server is enabled - Disabled servers don't sync to the agent
- Check tool descriptions - The AI uses descriptions to decide when to call tools. Make them clear and specific
- Test the connection - Ensure the server is reachable
Connection test passes but tools aren't working
- Verify input schema - Ensure the AI is sending parameters in the expected format
- Review server logs - Check your MCP server's logs for errors
- **Test tools directly **- Use the "List Tools" endpoint to verify tool availability
FAQ
Can I connect multiple MCP servers to one agent? Yes! You can connect up to 20 MCP servers to a single agent. Each server's tools will be available to the agent, and it will choose the appropriate tool based on the conversation context.
Can I use MCP servers behind a VPN? Currently, MCP servers must be accessible via public internet. For private networks, consider using a secure tunnel or API gateway that's publicly accessible with proper authentication.
Need Help?
📧 Email: [email protected] 💬 Chat: Use the in-app support widget
Updated 3 months ago