Start by checking the server URL, authentication, and the exact error. The hosted endpoint is https://mcp.agiler.io/v1, using Streamable HTTP and an Agiler API key in the Authorization: Bearer ... header.

The server will not connect

Check your client guide: ChatGPT, Claude, Claude Code, Codex, or Cursor.

  • Use the complete endpoint, including /v1, and an HTTP MCP connection.
  • Confirm the server is enabled and permitted by your organization’s client policy.
  • If the configuration uses an environment variable, make sure the client process receives it. An already-running desktop app may not inherit a variable set in a terminal.
  • Restart the connection after changing configuration.

Opening the endpoint in a browser sends a GET request and returns 405 Method Not Allowed; that is not a valid MCP connection test. Use the authenticated discovery and whoami examples in the reference setup section to test outside a client.

ChatGPT web’s custom-app flow cannot send Agiler’s static API-key header directly. Use the ChatGPT desktop setup or another supported client.

Authentication fails with 401

Agiler rejects missing, invalid, or revoked keys before processing MCP messages. Check that:

  1. You used an Agiler API key, rather than your AI provider’s key.
  2. The header is named Authorization and its value starts with Bearer followed by the complete key.
  3. The saved value has no placeholder text, extra quotes, or line breaks.
  4. The key is still present in the dashboard’s API Keys list.

For environment references, Claude Code uses ${AGILER_API_KEY}, Cursor uses ${env:AGILER_API_KEY}, and Codex’s bearer_token_env_var takes the name AGILER_API_KEY. A literal unresolved variable is not a valid token.

After fixing the credential, call whoami to verify the account. See key management if you need a replacement.

A tool is missing

The server exposes tools according to the key’s scopes. Ask the assistant to call whoami and inspect its effective scopes, then use scopes_list or the scope table to identify the permission needed.

For example, projects:read does not expose wp_run or sql_run; those need projects.wp:execute or projects.sql:execute. Grant the required scope and refresh the client’s tool catalog. Check whether the client has disabled the tool locally as well.

Revocations take effect on the next request, even if the client still displays a cached tool. Refresh after a permission change; the server does not require a new session.

A project is missing or access is denied

Scopes determine which operations a key can use. Resource restrictions and workspace permissions determine which projects it can access. Check all three in the dashboard. Do not broaden the key to every project just to fix a missing selection.

Verify the project identifier, inspect workspace membership, and check the key’s Project access selection. Follow pagination when listing projects. A 404 can also mean the resource was deleted or the identifier is incorrect.

Long-running operations

A client timeout does not prove that a SQL statement or WP-CLI command failed. Check history with sql_list or wp_list, then retrieve the operation with sql_get or wp_get before rerunning it.

For future calls, use async: true. Keep the returned id and pass it as statement to sql_get, or as command to wp_get, with the project identifier. Poll until the operation reports success, error, or cancelled. SQL can also report running before completion. Follow output pagination when needed.

Async execution lets you retrieve results across multiple calls; it does not remove execution limits. SQL and WP-CLI commands have a maximum execution time of 180 seconds. Cancelling a command does not undo work it already performed.

Other errors

ErrorNext step
400 / validation_errorCheck the tool’s argument names and required values. WP-CLI command text omits the leading wp; follow-up calls use the returned command UUID.
412 precondition_failedThe file’s current state does not match the write condition. Read it again, review the differences, and use the new ETag only after resolving the conflict.
413 Request Entity Too LargeReduce or split the request. Do not resend the same oversized payload.
429 Too Many RequestsWait for at least Retry-After, then retry with a delay between calls. Reduce concurrent work.
503 / project_provisioning or project_in_maintenanceCheck projects_get and wait for the project to be ready, respecting Retry-After when supplied.

Project deletion requires the current project name in confirm_name. Backup restoration requires the selected backup’s current created_at value in confirm_backup_created_at. Inspect the resource again if a confirmation is rejected; do not guess the value. These parameters acknowledge the target resource and do not replace your approval of the operation.

Get help

If the problem continues, contact us with the client and version, approximate time and timezone, tool name, project identifier, and redacted error output. Include whether whoami succeeds. Remove API keys, authorization headers, personal data, and sensitive site content from diagnostic material.