Skip to main content

Troubleshooting

Preview

The MCP integration is in preview - tools, parameters, and behavior may change between releases.

If something is not working, walk through this list before opening a support ticket. Most issues fall into one of a handful of categories.

Connection fails with 401 Unauthorized​

Cause: the X-API-KEY header is missing, malformed, or carrying a key that has been revoked.

What to check:

  • The header name is spelled exactly X-API-KEY (case-insensitive in practice, but stick to upper-case).
  • The value contains no surrounding quotes, whitespace, or Bearer prefix - it's a raw key.
  • The key still exists and has not been revoked in Administration → API Keys.
  • The key was created in the same environment you're calling.

Client cannot find any tools​

Cause: the URL or transport is misconfigured, so the client connected but never received the tool catalog.

What to check:

  • The URL ends with /mcp (e.g. https://sandbox.api.dimescheduler.com/mcp).
  • The transport is set to Streamable HTTP. Older stdio-only clients need the mcp-remote bridge.
  • The client was restarted after editing its configuration - most clients only re-read the config on startup.

If the MCP Inspector sees the tools but your real client doesn't, the issue is on the client side, not on the server.

"Resource not found" or "Task not found" errors​

Cause: the assistant called a tool with a name or identifier that does not match any record visible to the API key.

What to check:

  • The resource is referenced by display name, not employee number or email.
  • The user that owns the API key has permission to see the resource. Resource visibility filters apply to MCP requests just like they apply to the UI and the public API.
  • Capitalization and accents match. "José Garcia" and "Jose Garcia" are different display names.
  • For tasks and jobs, the format matches - TASK-001 is not the same value as 001.

Wrong data returned for "this week" / "tomorrow" / …​

Cause: the relative phrase was resolved against the wrong time zone or reference time.

What to do:

  • Make sure the assistant passes a timeZone parameter that matches the user's time zone, not the server's.
  • Encourage the assistant to call parse_relative_time before any tool that needs a concrete date range. Mixing relative phrases in the parameters of other tools is brittle.
  • Remember that weeks start on Monday. "This week" on a Sunday morning means the previous Monday → today's Sunday.

"I scheduled it on the wrong day"​

Cause: the user's prompt was ambiguous, the assistant guessed a date, and didn't ask to confirm.

What to do:

  • Add a system instruction to your assistant along the lines of "Always confirm the date, time, and resource before creating, updating, rescheduling, or deleting an appointment."
  • If you operate in a strictly controlled environment, point the MCP client at the sandbox environment first and rehearse common prompts before pointing it at production data.

The assistant calls get_recommendations when it should reschedule​

Cause: get_recommendations is the discovery tool - "find me a resource". reschedule_appointment is for moving existing work. Some prompts are ambiguous, and the model picks the wrong one.

What to do:

  • Use the keyword move or reschedule when you mean reassignment, and find or who is available when you mean discovery.
  • Add a system instruction that explicitly draws the line: "Use reschedule_appointment to change an existing appointment. Use get_recommendations only when the resource is not yet known."

Something else​

If none of the above apply:

  1. Reproduce the call against the MCP Inspector to isolate whether the issue is server-side or client-side.
  2. Capture the exact tool name, the parameters the assistant sent, and the response the server returned.
  3. Open a ticket through your usual support channel with that information attached.

The more concrete the report, the faster we can help.