Troubleshooting

The app does not start

• Confirm Docker and the Compose plugin are available.
• Copy the three example environment files before the first run; set pgAdmin credentials in the root .env.
• Check docker compose ps for services that are unhealthy or still starting.
• Read local service output with docker compose logs backend or the relevant service name.

The backend waits for PostgreSQL, the tool runner, and local resource-storage initialization. On a first launch, image builds and database migrations take time.

A client cannot connect

• Copy the exact endpoint URL and trailing slash from the server's Connect view.
• Use the hostname that matches where the client runs: host clients use the host-facing URL; Inspector in Compose uses http://backend:8000.
• Use Streamable HTTP. Managed MCP endpoints are protocol endpoints; opening one as a normal browser page is not a connection test.
• For hosted clients, confirm the public MCP origin and HTTPS configuration are correct.

Authentication fails

Do not confuse MCPKite's browser sign-in with an endpoint bearer token. A protected MCP server requires its assigned server token in the client's authorization header. That token is shown once when created; if it is lost, create or assign a new token.

For browser API requests from a separate UI origin, configure that exact origin in CORS_ALLOWED_ORIGINS. Credentialed CORS cannot use a wildcard, and cross-site authentication cookies are not supported.

A tool is missing or fails

• Confirm the tool is saved and the isolated runner is healthy. Without a healthy runner, saved tools remain unpublished drafts.
• Check that the function is top-level, all parameters are annotated, and a docstring is present.
• Call the tool with arguments matching its published input schema.
• Check the backend and runner logs for execution errors. Remember that runtime package installation is unavailable.
• Review operator-configured execution, source-size, output-size, and proxy limits.

A resource is missing

Verify the resource URI and, for templates, the requested URI parameter. A text resource uses matching double-brace placeholders in its body. A binary resource must be within 50 MiB, use a supported extension and MIME type, and have working object storage credentials.

Confirm the selected S3 or Azure provider is configured and the bucket or container is private but reachable by the backend. Local S3Mock and Azurite are development emulators, not production services.

Collect useful diagnostics

Start with the affected service's logs, such as docker compose logs backend or docker compose logs tool-runner. Reproduce with safe, representative inputs and record the time and failing endpoint path.

Before sharing diagnostics, remove cookies, Inspector launch URLs, authorization headers, server tokens, database passwords, workspace variable values, and secret values. Never include a secret in sample tool output.