Troubleshooting and Best Practices

Common status codes

• 401: expired cookie, wrong OpenAPI private key, or expired timestamp
• 403: insufficient role permissions
• 404: target resource ID does not exist
• 500: server failure or inconsistent database state

Recommended troubleshooting order

1. Verify that the MCP endpoint points to the correct environment.
2. Verify that MCP_SESSION_COOKIE is still valid.
3. Verify that the OpenAPI user ID matches the private key.
4. Verify that all referenced IDs exist.

Production guidance

• Create a dedicated API user for MCP access.
• Isolate keys by environment such as development, staging, and production.
• Keep audit logs for important tool calls.
• Add idempotency and rollback planning for write operations.