Work with the MCP server

This page explains how to work with the MCP server, including the prompts it exposes, suggested workflows, usage examples, and troubleshooting.

The MCP server maps tools to the DoiT developer API. Tool names and behavior follow the open-source @doitintl/doit-mcp-server package. After you connect, use your MCP client to list the tools the server currently exposes. The available set can change with the server version and your permissions.

MCP prompts

The MCP server can expose prompts as defined in the MCP prompts specification. Prompts are reusable playbooks your client can list in a prompt picker. Some prompts currently accept arguments, while others do not.

Note

The following example uses placeholder argument names (for example, project, cloud account, or date range) that may differ depending on your client. Some legacy prompts are being phased out as prompt definitions are standardized.

For example, spend on a specific Google Cloud service rises sharply over a week. Your MCP client shows a prompt like Review a cost spike for a cloud service. You can select it and supply the arguments the prompt defines (service name, project, start and end dates). The server returns prompt text that guides the model to use MCP tools, for example, narrow the window with get_anomaly or get_anomalies, then run a focused run_query or fetch a saved report with get_report_results, and to summarize likely drivers and follow-up checks. The same idea extends to AWS or multi-cloud cost views when that data is available through DoiT.

Clients discover prompts with prompts/list and retrieve content with prompts/get. On local stdio connections, the server supports the standard prompt flow, including arguments on the prompt definitions. Behavior may differ by transport or client version; use the latest @doitintl/doit-mcp-server if your client reports missing or invalid prompt handling.

Common workflows

These patterns help your AI assistant use the smallest reliable sequence of tools.

Reporting and saved reports

1. Optionally call validate_user if you need to confirm which account or tenant the session targets.
2. Call list_reports to find a saved report when the user names a dashboard or recurring report.
3. Call get_report_results once you know the report ID.

Prefer this path over run_query when a saved report already answers the question.

Ad hoc analytics queries

1. Call list_dimensions when grouping or filter fields are unclear.
2. Build a narrow query, then call run_query.
3. Refine and rerun if the first result is too broad.

Cost anomalies

1. Use get_anomalies for recent or top anomalies, or get_anomaly when the user already has an ID.
2. Use cloud, account or project, time range, and service from the anomaly before combining with other data sources.

Usage examples

Caution

The outputs and recommendations provided by the MCP server are generated dynamically and may vary based on the query. You should thoroughly review all outputs/recommendations to ensure they align with your organization's security best practices, cost-efficiency goals, and compliance requirements before implementation.

Your AI tool may be integrated with other MCP servers. To ensure your request yields the intended results, you should frame your request with relevant contextual cues for the DoiT MCP server. Some common queries that you might ask include: “What are my top 3 AWS services by cost”, “What are my recent cost anomalies”, “Show me the results of my Monthly Cost Overview report”, and “List all my invoices”.

In addition, you can use deep research when asking questions or making requests related to Cloud Intelligence data. This is useful as the MCP server can provide more granular insight into invoices, cost anomalies, resources, and so on. To do this using Claude:

1. Ask, for example: “What are my last 3 anomalies?”

2. Once you have the list, in the reply prompt, select Research.

3. In the reply prompt, ask for more in-depth information, for example: “Investigate number 3 — Cloud run anomaly — June 18, 2025. What caused it? How frequently does it happen? How can we prevent it from happening again?” Claude performs a deep dive into the anomaly.

Authorization and security

• Streamable HTTP: Uses a browser-based DoiT sign-in and consent flow. Local stdio: Authenticates with a personal API token via DOIT_API_KEY and does not use OAuth. Method details are under Connection methods. Client walkthroughs are under Client examples.

• Access control: MCP calls use your signed-in DoiT user (HTTP) or API token (stdio) and obey console permissions. You need the access described under Required permissions. Each tool follows the DoiT developer API authorization model for its underlying operation; see the API reference for operation-level requirements.

• Operational hygiene: If your organization changes your role or access, reconnect or retest the integration. For stdio, recreate or re-scope the API token if needed.

Troubleshooting

Symptom	Things to check
Connector or auth window does not open	For Streamable HTTP: browser pop-up blockers, corporate proxies, or extensions blocking OAuth or embedded flows. Retry after allowing the site. Local stdio does not open a browser; confirm DOIT_API_KEY is set instead.
Authorization with the MCP server failed with an ofid_ reference	The ofid_ reference is an identifier from the AI client (for example Claude or ChatGPT), not a DoiT error code. Confirm your organization's plan includes DoiT API access. Sign out and sign in again, then retry the connection. Confirm your user (or API token) has the permissions required for the tools you need; see the API reference.
Authentication fails (HTTP)	Sign-in did not complete or the session expired. Retry the browser sign-in flow.
Authentication fails (stdio)	DOIT_API_KEY is missing, invalid, expired, or not visible to the process that launches @doitintl/doit-mcp-server. Confirm the env value in your client config and recreate the personal API token if needed.
Access denied or empty data for expected resources	The signed-in user or API token lacks the Console permissions required for that API operation. Check the API reference and token scope.
Connected, but many tools are missing in the AI client	Some web-based MCP connectors expose only a subset of tools. Confirm you are not using the deprecated legacy SSE endpoint. Try the other supported connection method for your client, or a client that loads the full tool list.
Unexpected tool errors	Confirm the API reference for the tool you are using; parameters and quotas apply the same as for direct API calls.
Inline widget does not render in Claude Cowork	Inline widget rendering (such as Cloud Analytics charts) requires a hosted remote MCP server connection. Local stdio connections do not support widget metadata. Ensure you are connected via the remote server. Tool results still return correctly as text even when widget rendering is unavailable.