Skip to main content

Answer questions about a website using your own Firecrawl account

Section: DOC-IN-tools-connections-custom-mcp-servers#bring-your-own-mcp-server.

Let a customer ask your assistant to read a public page and explain what it says. This recipe uses a Firecrawl account you already own: store its credential, register its MCP endpoint, test discovery, and use it in a conversation. The same connection pattern applies to a compatible MCP server for a service you operate.

If you want Travila's available web tools without a separate vendor account, use the web-research recipe. If the action must run inside your application or private network, use a client tool.

Prepare a test question and account​

Section: DOC-IN-tools-connections-custom-mcp-servers#what-you-need.

You need a Firecrawl credential permitted to read the chosen public site, a backend Travila key, a test application user and an existing conversation. Choose a page you can inspect yourself and a question whose answer appears on it. This lets you check the final answer against the source.

Follow Firecrawl’s API-key MCP setup for the vendor endpoint and bearer credential used below. The server must offer Streamable HTTP at a publicly reachable HTTPS endpoint. Travila cannot launch a local process or dial your private-network endpoint for this recipe. Custom-server configuration currently belongs to the tenant's default project; a supplied X-Project-Id does not create project or test/live isolation. Use an isolated tenant for testing when required.

1. Store the Firecrawl credential​

Section: DOC-IN-tools-connections-custom-mcp-servers#store-the-credential.

Run this from your backend, replacing the placeholder with your credential:

curl -X POST https://api.travila.ai/api/v1/secrets/put \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "firecrawl-api-key",
  "value": "fc-your-token-here",
  "description": "Firecrawl bearer token",
  "labels": {
    "kind": "mcp-auth"
  }
}'

Reference: Create or update a secret · Request fields.

The response contains metadata, not the stored value. Keep the name firecrawl-api-key for the next step. Registration rejects a reference to a secret that does not exist.

Only your trusted backend should hold this Travila key: current secret APIs do not restrict a key to one named secret, so a key that can use them can overwrite or delete other project credentials. Keep the Firecrawl credential out of agent instructions and public endpoint URLs.

2. Register the service you want Travila to call​

Section: DOC-IN-tools-connections-custom-mcp-servers#register-the-server.

curl -X POST https://api.travila.ai/api/v1/mcp-servers/create \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "server": {
    "serverId": "firecrawl",
    "displayName": "Firecrawl",
    "description": "BYO web scraping MCP",
    "endpoint": "https://mcp.firecrawl.dev/v2/mcp",
    "authType": "CUSTOM_MCP_SERVER_AUTH_TYPE_BEARER",
    "authSecretRef": {
      "name": "firecrawl-api-key"
    },
    "enabled": true,
    "requestTimeout": "30s"
  }
}'

Reference: Register a custom MCP server · Request fields.

Keep the returned server ID, firecrawl. Configuration calls use this bare ID and a backend key without X-On-Behalf-Of. Later conversation calls use custom:firecrawl and the authenticated application user.

The saved record contains authSecretRef, not the credential. Confirm the endpoint and enabled state in the response before continuing. Registration alone does not give every agent access to this server.

Adapt the connection for another service​

Section: DOC-IN-tools-connections-custom-mcp-servers#authentication-modes.

Match the service's documented authentication method when adapting this recipe. The create-server reference describes bearer, named-header, query-parameter and no-auth modes and their required fields. An omitted authentication mode is rejected.

For a provider that requires a key in a query parameter, store the value as a secret and configure the parameter name through query authentication. Do not put the value in the saved endpoint URL: get/list return that URL. Restrict access to diagnostic errors too; provider errors may echo credentials in forms that are not fully sanitized.

Connect only a server intended for this customer task​

Section: DOC-IN-tools-connections-custom-mcp-servers#egress-guard.

Use a public HTTPS service you trust with the tool arguments it will receive. Private, loopback and local-only destinations are rejected, and cross-host redirects are not followed. See the server reference for accepted configuration.

A successful connection does not make a server suitable for customer data. In particular, an administrative tool connected with developer-wide credentials may expose more than the user's task requires. Give this integration a credential and tool selection appropriate to the data it will read.

3. Check the saved connection and choose its tools​

Section: DOC-IN-tools-connections-custom-mcp-servers#test-it-before-you-rely-on-it.

curl -X POST https://api.travila.ai/api/v1/mcp-servers/test-connection \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "serverId": "firecrawl"
}'

Reference: Test a custom MCP server connection · Request fields.

A successful test reports the discovered tool count:

{
  "success": true,
  "toolCount": 26,
  "latencyMs": "556"
}

Reference: Test a custom MCP server connection · Response fields.

Inspect whether the connection test actually succeeded. Fix the endpoint, credential or network problem before asking the assistant to repeat the whole research task.

Inspect the names before setting filters or approvals​

Section: DOC-IN-tools-connections-custom-mcp-servers#tool-names-are-not-namespaced.

curl -X POST https://api.travila.ai/api/v1/llm/mcp-list-tools \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "servers": [
    {
      "serverId": "custom:firecrawl",
      "enabled": true
    }
  ]
}'

Reference: List available MCP tools · Request fields.

Choose the tools needed to read the test page using the returned names and input schemas. The server ID is custom:firecrawl; tool names are whatever the server advertises. Do not prepend that server ID to a tool name when creating allow/block or approval patterns.

Select tools with distinct names when using multiple servers; registration does not reject duplicate tool names across servers. A successful connection test establishes discovery, not authorization for every tool it offers.

4. Ask about the page in a conversation​

Section: DOC-IN-tools-connections-custom-mcp-servers#give-it-to-the-model.

Use the server for a single turn with overrideMcpServers. Replace the conversation key and page URL with your test values:

curl -X POST https://api.travila.ai/api/v1/llm/send-message \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "support-chat-001",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Read https://www.firecrawl.dev/pricing and summarize the pricing options. Link to the source."
      }
    ]
  },
  "overrideMcpServers": [
    {
      "serverId": "custom:firecrawl",
      "enabled": true
    }
  ]
}'

Reference: Send a message to a conversation · Request fields.

The prompt is an illustrative customer task, not a promise that a page's content or pricing remains unchanged. The assistant chooses from the selected server's discovered tools. Use your chosen tool names in allowlistToolPatterns when restricting the task; a non-empty server override replaces inherited server selections and their filters.

Read the run outcome and tool-call record, then compare the answer with the page. The recipe is complete when a successful read from the intended server supports the answer. If the page could not be fetched, show that failure rather than presenting the assistant's recollection as retrieved content.

For repeated use, add the server to the appropriate agent profile or conversation settings. Configure approval rules before exposing tools that perform sensitive actions.

Keep the integration working​

Section: DOC-IN-tools-connections-custom-mcp-servers#managing-servers.

Use these maintenance steps when the website-reading feature is already in use. Inspect saved configuration with get-server, and use list-servers with authSecretNameFilter to find every server depending on a credential. Include disabled servers when checking that dependency list.

Move or change the server​

Section: DOC-IN-tools-connections-custom-mcp-servers#updating-is-a-full-replace.

Read the saved definition, apply the intended change to that complete record, then submit it through update-server.

Read the record again and test the connection. A saved version confirms the configuration update, but it does not establish that every call has adopted it or cancel calls already in progress.

Rotate the credential​

Section: DOC-IN-tools-connections-custom-mcp-servers#rotating-a-credential.

First find dependent servers. Then replace the named secret using the same name:

curl -X POST https://api.travila.ai/api/v1/secrets/put \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "firecrawl-api-key",
  "value": "fc-the-new-token"
}'

Reference: Create or update a secret · Request fields.

Inspect secret metadata and test the connection. Metadata alone cannot prove the stored value after a partially failed write. A successful connection shows that this test was accepted; the API does not report when all calls have switched credentials.

Coordinate the cutover with your operator before retiring the old credential at Firecrawl. Updating the stored value does not revoke the old one at its issuer. For urgent revocation, revoke at the issuer and account for the resulting interruptions.

Stop using the service​

Section: DOC-IN-tools-connections-custom-mcp-servers#disabling-vs-deleting.

Remove dependent conversation/profile references when retiring the feature. To keep the configuration for later, update the complete server record with enabled: false. To remove it, call delete-server.

After deletion is observed, new resolution fails. Neither disabling nor deleting recalls an in-flight call or definitions already loaded for it. Deleting a server leaves the referenced secret in place.

Retire the unused credential​

Section: DOC-IN-tools-connections-custom-mcp-servers#retiring-a-credential.

Check the server dependency list before deleting the secret. A still-referenced secret returns 409 by default. Update or remove those references first; forced deletion intentionally leaves dependent servers unable to authenticate.

Confirm that the obsolete credential is also revoked at its issuer. Deleting Travila's copy does not invalidate a credential held elsewhere.

Plan for slow or unavailable pages​

Section: DOC-IN-tools-connections-custom-mcp-servers#limits.

Choose a supported request timeout that fits how long the customer can wait for the page. Keep an unavailable lookup visible instead of promising a completed research answer.

If the feature stops working, test the connection, inspect the original call and distinguish authentication failure from a page-specific failure. Do not repeatedly rerun the entire customer task to diagnose it.

Section: DOC-IN-tools-connections-custom-mcp-servers#related.

Document ID: DOC-IN-tools-connections-custom-mcp-servers. Section identities and revisions.