Symptom: Your AI assistant reports that it cannot connect to Ferrule, or the MCP connection times out during setup.

Cause: The MCP endpoint URL is incorrect, the Ferrule service is not running, or a firewall is blocking outbound HTTPS on port 443.

Solution:

1. Confirm the MCP URL ends with /api/mcp (not /sse): https://app.ferrule.io/api/mcp.
2. Test connectivity with curl:

   curl -I https://app.ferrule.io/api/mcp {"\n"}  -H "Authorization: Bearer <your-api-key>"

   A 200 OK or 405 Method Not Allowed response confirms the host is reachable.
3. If using the SSE transport (legacy clients), the endpoint is /sse.
4. Check that port 443 is open outbound from the machine running your AI assistant.

See Getting Started to verify your MCP URL.

Symptom: Every REST request returns {"error":"Unauthorized"} with HTTP 401.

Cause: The API key is missing, malformed, or has been revoked.

Solution:

1. Confirm the Authorization header is present and formatted correctly:

   Authorization: Bearer frl_...

2. Verify the key has not expired. In the Ferrule dashboard, go to API Keys and check the Expires column. If it shows "Expired," generate a new key.
3. Check that the key was not revoked. A revoked key does not appear in the dashboard list.
4. Ensure there are no extra spaces or newline characters around the token value.

Symptom: Requests return HTTP 403 even though the API key is valid.

Cause: The API key belongs to a member whose custom role does not grant access to the requested integration, or the integration has REST protocol disabled.

Solution:

1. Open Dashboard → Integrations → Configure for the affected integration and confirm REST is toggled on. REST is disabled by default for new integrations.
2. If your account has a custom role, ask an admin to verify the role includes the integration you are trying to call. See Organizations & Teams for role details.
3. Admins and owners always have full access — if an admin's key is returning 403, the issue is the protocol toggle, not the role.

Symptom: Requests intermittently return HTTP 429 with a Retry-After header.

Cause: Ferrule enforces a rate limit of 100 requests per minute per API key. Bursts of automation or a tight polling loop can exceed this limit.

Solution:

1. Read the Retry-After response header; it contains the number of seconds to wait before retrying.
2. Add exponential backoff to your client: start with a 1-second delay and double it on each retry, up to a maximum of 60 seconds.
3. If you legitimately need a higher rate limit, contact Ferrule support.
4. Check whether multiple scripts or processes share the same API key — each one counts against the same limit. Consider generating separate keys per process.

Symptom: Connection works from one network but fails from a corporate network or CI environment.

Cause: A firewall or HTTP proxy is intercepting HTTPS connections to the Ferrule host.

Solution:

1. Check whether your environment requires an HTTP proxy. Set the standard proxy environment variables if so:

   export HTTPS_PROXY=http://proxy.example.com:3128

2. If your proxy performs TLS inspection (MITM), you may need to add the proxy's CA certificate to your trust store.
3. Contact your network administrator to whitelist the Ferrule host.