MCP setup

BlueSuite's Model Context Protocol (MCP) server exposes business operations as tools. Reads and writes use the connected workspace; changes appear in the dashboard and mobile app.

Connect with ChatGPT

1. Open the BlueSuite ChatGPT app. ChatGPT lists it in its Plugins directory.
2. Install it using the install or + control, then connect the BlueSuite account when prompted.
3. Sign in to BlueSuite, select the workspace you want to use, and review the requested access before authorizing.
4. Start a new chat. Type @BlueSuite and select the app to use it in the conversation.
5. Try: “Use BlueSuite to show my jobs scheduled for tomorrow.”

The published app handles the MCP connection for you. You do not need to enter a server URL or create an API key for this setup. You need an existing BlueSuite account; create one here if needed.

Installation and connection controls can vary by ChatGPT account and workspace. If the app is unavailable in a managed workspace, ask your ChatGPT administrator to enable it. See OpenAI's plugin installation guide for current host instructions.

Connect with Claude

Use a remote custom connector in Claude on the web or Claude Desktop:

1. Open Customize > Connectors and choose Add custom connector.
2. Name it BlueSuite and enter https://my.bluesuite.app/api/mcp as the remote MCP server URL.
3. Continue with OAuth authentication and choose Sign in now. If Claude asks how to identify the OAuth client, use Register automatically.
4. Finish adding the connector, sign in to BlueSuite, and authorize the intended workspace. If it is not connected yet, select Connect beside BlueSuite.
5. Enable BlueSuite from the conversation's + > Connectors menu, then ask: “Use BlueSuite to list my outstanding invoices.”

For Claude Team or Enterprise, an authorized organization owner or administrator must add the connector under Organization settings > Connectors before members connect their accounts. See Claude's custom connector guide for current controls and availability.

Remote connection

Add this server URL to a client that supports Streamable HTTP:

https://my.bluesuite.app/api/mcp

Use OAuth when your host supports discovery. Complete authorization and select a workspace. The server advertises its protected-resource metadata in an unauthenticated response's WWW-Authenticate header. You can also read it at /.well-known/oauth-protected-resource/api/mcp on the same host.

For a trusted client using an API key, configure this request header:

Authorization: Bearer wk_<workspace_hash>.<secret_key>

Choose the resource scopes your tools need. Connecting and discovering tools does not grant permission to execute them; underlying API scopes, workspace features, and user permissions still apply. See authentication.

Transport behavior

The remote server is stateless. Send MCP messages over POST with the JSON headers and protocol negotiation your MCP client provides. It does not support the legacy standalone SSE GET transport: GET returns 405. DELETE also returns 405 because there is no persistent session to terminate.

A protocol-level discovery sequence is:

1. Send initialize and read the server capabilities and instructions.
2. Complete the MCP initialization handshake.
3. Call tools/list to get the current tools and schemas.
4. Use tools/call with a tool name and arguments.

Use an MCP client library or a host's built-in connector for the handshake. The tool reference describes every registered tool. If a host caches tool discovery, refresh or reconnect after additions; a published integration can expose an older approved snapshot.

First call

For a concrete request, use the relevant tools directly. If a newly connected user only says hello or asks what they can do, call get_started with an empty arguments object. It suggests useful starting actions based on the account.

Use get_workspace for timezone and workspace context, and resolve names with the appropriate list_* tool before passing IDs. See workflow rules.

Inputs, results, and errors

All tools reject unknown top-level argument names, including tools that take no arguments. Numeric IDs must be positive; user IDs are UUIDs. Some schemas allow numeric-string coercion and date normalization, but callers should send the canonical types and formats shown in the reference.

Tool results include text content and matching structuredContent, usually shaped as { "data": ... }. Lists can also include pagination. Help and onboarding tools return text in data; entity records allow additional fields rather than promising a fixed database schema.

Check isError before interpreting a result as success. Invalid inputs can also produce protocol errors. Field-level messages describe what to correct; do not retry with invented business details. API authorization, state conflicts, and rate limits still apply to tool calls.

MCP schemas as JSON include each tool's complete input/output contract.

Local stdio server

Repository-based integrations can run the stdio server locally:

npm run build --workspace=@bluesuite-app/mcp-server
BLUEPRO_API_KEY="$BLUESUITE_API_KEY" \
BLUEPRO_API_URL="https://my.bluesuite.app" \
node packages/mcp-server/dist/index.js

Run this from an installed checkout. The two environment variable names retain the former product name for compatibility; they must be spelled exactly as shown. Set the URL explicitly: the local server defaults to http://localhost:3000.

In a host's stdio configuration, use node as the command, the absolute path to packages/mcp-server/dist/index.js as its argument, and those environment values in its secret/environment configuration. This private workspace package is not an installable public npm package.

Troubleshooting

• A browser GET returning 405 does not mean the MCP server is down. Configure Streamable HTTP POST.
• A missing tool can be a cached host snapshot. Refresh discovery.
• A discovered tool returning 403 needs the appropriate permissions, scopes, or enabled module.
• If the wrong workspace is selected, reconnect and authorize the intended workspace.
• For help using the product, use list_help_guides and get_help_article.