MCP server integration
Connect your agent to external tools, data sources, and services using the Model Context Protocol (MCP). MCP is an open standard, developed by Anthropic, that standardizes how AI applications talk to external systems: a universal adapter that lets your agent interact with anything that speaks MCP.
Connect a server
Section titled “Connect a server”- 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
Section titled “Configuration reference”The core settings required to connect to an MCP server.
Display name
Section titled “Display name”A friendly name to identify this server in your dashboard.
Example: "Customer Database" or "Logistics API"Base URL
Section titled “Base URL”The root URL of your MCP server.
Example: https://mcp.yourcompany.comMust be a valid URL with an http:// or https:// protocol. Use HTTPS in production.
Connection type
Section titled “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
Section titled “Endpoint path”The path on the server where MCP requests are sent.
| Connection Type | Default Path |
|---|---|
| Streamable HTTP | /mcp |
| SSE | /sse |
API key / secret token
Section titled “API key / secret token”Authentication token for your MCP server, if required.
Example: sk-xxxxxxxxxxxxxxxxxxxxTokens are encrypted at rest and never displayed in the UI after saving. To update a configuration without changing the token, leave this field empty.
Advanced settings
Section titled “Advanced settings”These optional settings fine-tune your integration.
Forward user context
Section titled “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 identity 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 headers:
X-Foldspace-User-Id: user_abc123X-Foldspace-Subscription-Id: sub_xyz789Custom headers
Section titled “Custom 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 |
Test your integration
Section titled “Test your integration”Test the connection before saving to confirm everything works.
Test the connection
Section titled “Test the connection”The Test Connection button performs a full MCP initialization handshake with your server.
| Result | Meaning |
|---|---|
| Success | Server is reachable and responds correctly to the 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 the server is running and the 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 the server implements the MCP protocol correctly |
View available tools
Section titled “View available tools”After a successful connection test, click View Available Tools to see what 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.
Limits and quotas
Section titled “Limits and 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
Section titled “Troubleshooting”My agent isn’t using the MCP tools
Section titled “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
Section titled “Connection test passes but tools aren’t working”- Verify the 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.
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 are available to the agent, which chooses the appropriate tool based on the conversation context.
Can I use MCP servers behind a VPN? Currently, MCP servers must be accessible via the public internet. For private networks, use a secure tunnel or API gateway that’s publicly accessible with proper authentication.
Get help
Section titled “Get help”- Email support@foldspace.io.
- Use the in-app support widget.