> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubblav.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Servers

> Connect to Model Context Protocol servers for advanced AI capabilities

MCP (Model Context Protocol) servers extend your chatbot with standardized AI capabilities. Unlike custom tools that connect to your APIs, MCP servers provide pre-built tools following an open protocol.

## What is MCP?

Model Context Protocol is an open standard for connecting AI systems to external tools and data sources. MCP servers expose:

* **Tools**: Actions the AI can perform
* **Resources**: Data the AI can access
* **Prompts**: Pre-defined conversation templates

<Info>
  MCP is an advanced feature. Most users should start with [Integrations Overview](/user-guide/integrations/overview) or [Custom Tools](/user-guide/integrations/custom-tools).
</Info>

## When to Use MCP vs Custom Tools

| Feature | Custom Tools | MCP Servers |
| - | - | - |
| Setup complexity | Simple | Advanced |
| Protocol | HTTP/REST | MCP (SSE over HTTP) |
| Best for | Your own APIs | Pre-built AI tools |
| Authentication | Built-in options | Server-specific |

**Use Custom Tools when:**

* Connecting to your own backend
* Simple API integrations
* Need built-in auth options

**Use MCP when:**

* Using pre-built MCP servers
* Need advanced AI capabilities
* Building with MCP ecosystem

***

## Adding an MCP Server

<Steps>
  <Step title="Navigate to MCP Servers">
    Go to **Dashboard** → **Integrations** → **MCP Servers** → **Add Server**
  </Step>

  <img className="block dark:hidden" src="https://mintcdn.com/bubblav-e553cf80/nhelQxnCmiOq_LRR/images/integrations-mcp.png?fit=max&auto=format&n=nhelQxnCmiOq_LRR&q=85&s=52796ecf1744cac40460c8d184b161cf" alt="MCP Servers Overview" width="899" height="393" data-path="images/integrations-mcp.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/bubblav-e553cf80/nhelQxnCmiOq_LRR/images/integrations-mcp-dark.png?fit=max&auto=format&n=nhelQxnCmiOq_LRR&q=85&s=0fe9218d7954d4fc0d3c6f2ab02c6502" alt="MCP Servers Overview" width="901" height="430" data-path="images/integrations-mcp-dark.png" />

  <Step title="Configure Server">
    Fill in the server configuration:

    **Server Name** (required)

    * A friendly name for this server
    * Example: "File Browser", "Database Query"

    **Server URL** (required)

    * The MCP server endpoint URL using Server-Sent Events (SSE)
    * Example: `https://mcp.example.com/sse`
    * Must be accessible over HTTPS
  </Step>

  <Step title="Choose Authentication Mode">
    Pick how BubblaV authenticates against the server:

    **Headers / API key** (default)

    * Add custom headers if the server requires them
    * **Header Key**: e.g., `Authorization`, `X-API-Key`
    * **Header Value**: Your authentication token or key
    * Common examples: `Authorization: Bearer your-token-here`, `X-API-Key: your-api-key`

    **OAuth login**

    * For MCP servers that support OAuth 2.1 (e.g. [Spoks](https://mcp.spoks.com/mcp))
    * No headers or tokens to copy — BubblaV discovers the server's OAuth endpoints and registers itself automatically
  </Step>

  <Step title="Save and Connect">
    * **Headers mode**: save, then click **Refresh** to fetch the server's tools.
    * **OAuth mode**: save and you are redirected to the provider's sign-in/consent screen. Approve access — BubblaV stores the tokens encrypted, syncs the server's tools, and returns you to the dashboard. Tokens refresh automatically before they expire.
  </Step>
</Steps>

***

## Configuration Examples

### Remote MCP Server

Connect to a remote MCP server with authentication:

| Field | Value |
| - | - |
| Name | Custom Server |
| URL | `https://mcp.example.com/sse` |
| Headers | `Authorization: Bearer your-token-here` |

### OAuth MCP Server

Connect with one-click OAuth instead of headers:

| Field | Value |
| - | - |
| Name | Spoks Marketing |
| URL | `https://mcp.spoks.com/mcp` |
| Authentication | OAuth login |

### Public MCP Server

Connect to a public MCP server without authentication:

| Field | Value |
| - | - |
| Name | Public Tools Server |
| URL | `https://public-mcp-server.com/sse` |
| Headers | (none required) |

***

## Available Tools

After connecting, the server's tools appear in your dashboard. Common tool types:

* **File operations**: Read, write, list files
* **Database queries**: SQL or natural language queries
* **Web scraping**: Fetch and parse web content
* **API integrations**: Pre-built API connectors

Each tool shows:

* Name and description
* Required parameters
* Return type

***

## Managing MCP Servers

### View Connected Servers

Go to **Dashboard** → **Integrations** → **MCP Servers** to see:

* Connection status
* Available tools
* Last activity

### Disconnect

1. Find the server card
2. Click the settings icon
3. Select **Disconnect**

### Reconnect

If a server disconnects:

1. Check the server is running
2. Verify configuration
3. Click **Reconnect**

OAuth servers also show a **Connect** / **Reconnect** button on their card. Use it when the authorization expired or was revoked on the provider side — it restarts the OAuth consent flow.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server won't connect">
    * Verify the server URL is correct and accessible
    * Check that the server supports SSE (Server-Sent Events) transport
    * Review authentication headers if required
    * Ensure the server is running and reachable over HTTPS
  </Accordion>

  <Accordion title="Tools not appearing">
    * Wait for server initialization
    * Check server logs for errors
    * Verify server exposes tools correctly
  </Accordion>

  <Accordion title="Connection drops">
    * Check network stability and HTTPS connectivity
    * Verify the server URL is still valid
    * Review server health and availability
    * Check authentication headers haven't expired
  </Accordion>

  <Accordion title="OAuth connect fails">
    * If you denied the consent screen, click **Connect** on the server card and approve access
    * Confirm the server advertises OAuth support (most hosts expose `/.well-known/oauth-protected-resource`)
    * A `mcp_oauth_failed` error usually means the provider rejected automatic client registration — contact the server provider
  </Accordion>
</AccordionGroup>

***

## Security Considerations

<Warning>
  MCP servers can execute code and access data. Only connect trusted servers.
</Warning>

* **Verify sources**: Only use official or audited MCP servers
* **Limit access**: Configure minimal permissions
* **Monitor activity**: Review tool usage in logs
* **Encrypted tokens**: OAuth tokens and header secrets are stored encrypted at rest, never returned by the API, and refreshed server-side before expiry
* **HTTPS only**: Always use HTTPS URLs to protect data in transit

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Custom Tools" icon="wrench" href="/user-guide/integrations/custom-tools">
    Build simple API integrations
  </Card>

  <Card title="Integrations Overview" icon="puzzle-piece" href="/user-guide/integrations/overview">
    Connect popular platforms
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.