Connecting MCP Servers

Connect an MCP server to Obvious so the agent can call its tools.

Model Context Protocol (MCP) is an open standard for exposing tools and resources to AI assistants. When you add an MCP HTTP server to Obvious, the agent can call any tool that server exposes — database lookups, internal APIs, custom search endpoints, whatever your server provides.

What you will need

• An MCP-compatible HTTP server reachable over HTTPS. The server must accept MCP requests over HTTP (not stdio).
• The server's URL.
• For URL-based auth types (bearer token, API key, or custom header): the credentials your server requires. For OAuth: nothing beyond the URL — Obvious handles discovery and registration automatically.

Add an MCP server

1. Open Settings → Connections.
2. Click Add MCP Server.
3. Enter the server's URL in the Server URL field.
4. Under Authentication, select the type that matches your server:
   • None — no authentication required
   • Bearer token — sent as Authorization: Bearer token
   • API key — sent as X-API-Key: key
   • Custom header — enter your own header name and value
   • OAuth — Obvious discovers the authorization server and registers a client automatically
5. Enter any required credentials for the auth type you selected. OAuth requires no credentials at this step.
6. Click Connect.

Once saved, the modal stays open so you can optionally test the connection. Click Test connection to verify Obvious can reach the server. You'll see a confirmation or an error message inline. Click Close when you're done.

Connect via OAuth

If your MCP server uses OAuth, select OAuth as the authentication type after entering the server URL. Obvious takes care of server discovery and client registration — you do not need to create an OAuth application or manage any credentials manually.

After you click Connect, Obvious discovers the authorization server and registers a client automatically — you do not configure anything on the OAuth provider side. A popup window opens with the provider's authorization page.

1. Approve access in the popup when prompted.
2. The popup closes. The modal updates to confirm the connection is active.

You have a 5-minute window to complete the authorization. If the popup is closed or the authorization times out, the connection fails — see Troubleshooting below.

Once connected, the OAuth connection appears in Settings → Connections alongside your other MCP servers. You can edit or remove it the same way as any other connection.

How the agent uses MCP tools

Once connected, the agent discovers the tools your server exposes and can call them in response to your requests. You do not need to configure anything in the project — the tools are available automatically in any project where the connection is in scope.

For example, if your MCP server exposes a search_product_catalog tool, you could ask:

Find all products in the catalog under $50

The agent calls the tool, formats the results, and responds — just like any other operation.

Note: The agent uses MCP tools when your request matches what they can do. If you're not seeing expected tool behavior, try being more specific — naming the data source or action often helps the agent pick the right tool.

Manage a connection

Open Settings → Connections at any time to:

• Edit — Update the server URL or credentials. Click the ⋮ menu on the connection and select Edit.
• Remove — Click the ⋮ menu and select Remove. The agent loses access to that server's tools immediately.

Troubleshooting

The server will not connect. Make sure the URL is correct and the server is running and reachable over HTTPS. Obvious requires a valid TLS connection — plain HTTP endpoints will not work. If the server is behind a firewall or VPN, it needs to be accessible from Obvious's infrastructure.

Authentication is failing. Check that you selected the right auth type and entered the credentials exactly as your server expects. If you're using a bearer token, make sure you're entering the raw token — Obvious adds the Bearer prefix automatically. For API key auth, the key goes in as-is. After updating credentials, remove and re-add the connection to force a fresh auth attempt.

The popup was blocked. Allow popups from app.obvious.ai in your browser settings, then remove the connection and try again.

You denied consent or closed the popup. The connection attempt fails if you deny access or close the popup before approving. Remove the connection from Settings → Connections and add it again to start a new authorization flow.

The OAuth authorization timed out. The authorization window stays open for 5 minutes. If it expires before you complete the flow, remove the connection and add it again.

The agent is not using the server's tools. Confirm the connection shows as active in Settings → Connections. If it shows an error, try removing it and re-adding with the correct URL and credentials. If the connection looks healthy but the agent still is not calling the tools, try asking explicitly — for example, "Use the [server name] tools to search for X."

The connection was working and stopped. If your server URL changed or the server restarted with a new endpoint, remove the existing connection and add it again with the updated URL. If only credentials changed, edit the connection and re-enter them. If an OAuth connection stops working unexpectedly, remove it from Settings → Connections and re-add it to re-authorize.

If you're still running into issues, reach out to help@obvious.ai and include the server URL (minus any credentials) and a description of what you're seeing.