# Model Context Protocol (MCP) {% hint style="warning" %} This feature is only enabled on certain environments and tenants. Please contact [Support](/support/support.md) for more information about this feature. {% endhint %} {% hint style="info" %} This feature is a work in progress. Please contact [Support](/support/faq.md) if you have any questions or feedback. {% endhint %} Model Context Protocol (MCP) enables AI systems to securely connect to external tools and data. In the context of Coherent Spark, MCP allows AI agents to interact directly with Spark-generated APIs, unlocking agentic use cases that build on existing Excel logic. To support this, Coherent provides a remote MCP server that clients can use to integrate Spark into AI-driven workflows. {% embed url="" %} ## Prerequisites Before connecting to the Coherent MCP server, make sure you have the following: * Access credentials to a Spark tenant. Access can be authenticated using either: * User login. * Authorization token: This can be retrieved from the [Navigation menu](/navigation/navigation-menu.md#user-menu). * MCP-compatible AI client: e.g. [Claude](https://www.claude.com/), [Cursor](https://www.cursor.com/), [Visual Studio Code](https://code.visualstudio.com/), etc. ## Connect to the Coherent MCP Server This guide explains how to connect your AI client to the Coherent MCP server to access Coherent Spark tools and capabilities. ### Configure for Claude #### Claude desktop The [Claude desktop](https://support.claude.com/en/collections/16163169-claude-desktop) apps bring Claude's capabilities directly to your computer, allowing for seamless integration with your workflow. 1. Follow the instructions in [Custom connectors](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities#h_b7263f8086). * Name: `coherent-spark` * Remote MCP server URL: `https://mcp.{environment}.coherent.global/{tenant}/mcp`, replacing `{environment}` and `{tenant}`, with your specific environment and tenant details. * If Custom connectors are not available, they may need to be provisioned by the plan owner. 2. Click **Connect** and you will be prompted for a Coherent Spark login. #### Claude code CLI [Claude Code](https://code.claude.com/docs/) is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Reference [Add a remote HTTP server](https://code.claude.com/docs/en/mcp#option-1-add-a-remote-http-server). {% tabs %} {% tab title="User login authentication" %} Update `myenvironment` and `mytenant` then submit. When trying to access the server, you will be prompted for a Coherent Spark login. ```bash claude mcp add --transport http coherent-spark https://mcp.myenvironment.coherent.global/mytenant/mcp ``` {% endtab %} {% tab title="Authorization token" %} Update `myenvironment`, `mytenant`, and `{token}` then submit. ```bash claude mcp add --transport http coherent-spark https://mcp.myenvironment.coherent.global/mytenant/mcp --header "Authorization: Bearer {token}" ``` {% endtab %} {% endtabs %} ### Configure for Cursor [Cursor](https://cursor.com/) is an AI-assisted integrated development environment for Windows, macOS, and Linux. It is a fork of [Visual Studio Code](https://code.visualstudio.com/) with additional AI features. Reference [Model Context Protocol (MCP)](https://cursor.com/docs/mcp). 1. Open *Cursor Settings*, *Tools & MCP*. 2. Click **Add Custom MCP**. 3. Add the appropriate snippet from below based upon your choice of authentication. 4. For Cursor, it is recommended to restart the application to use the new Custom MCP. {% tabs %} {% tab title="User login authentication" %} If you do not have any MCP servers configured, add the following snippet into the document. If you already have other MCP servers defined, add `coherent-spark` into `mcpServers{}`. Update `myenvironment` and `mytenant` then save. When trying to access the server, you will be prompted for a Coherent Spark login. ```json { "mcpServers": { "coherent-spark": { "url": "https://mcp.myenvironment.coherent.global/mytenant/mcp" } } } ``` {% endtab %} {% tab title="Authorization token" %} If you do not have any MCP servers configured, add the following snippet into the document. If you already have other MCP servers defined, add `coherent-spark` into `mcpServers{}`. Update `myenvironment`, `mytenant`, and `{token}` then save. ```json { "mcpServers": { "coherent-spark": { "url": "https://mcp.myenvironment.coherent.global/mcp", "headers": { "Authorization": "Bearer {token}" } } } } ``` {% endtab %} {% endtabs %} ### Configure for Visual Studio Code [Visual Studio Code](https://code.visualstudio.com/) (commonly referred to as VS Code) is an integrated development environment developed by Microsoft for Windows, Linux, macOS and web browsers. Reference [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). 1. Open the Command Palette (`Ctrl+Shift+P` or `F1`). 2. Select the command *MCP: Open User Configuration.* 3. Add the appropriate snippet from below based upon your choice of authentication. 4. From the editor you can *Start* the server. {% tabs %} {% tab title="User login authentication" %} If you do not have any MCP servers configured, add the following snippet into the document. If you already have other MCP servers defined, add `coherent-spark` into `servers{}`. Update `myenvironment` and `mytenant` then save. When trying to access the server, you will be prompted for a Coherent Spark login. ```json { "servers": { "coherent-spark": { "type": "http", "url": "https://mcp.myenvironment.coherent.global/mytenant/mcp" } } } ``` {% endtab %} {% tab title="Authorization token" %} If you do not have any MCP servers configured, add the following snippet into the document. If you already have other MCP servers defined, add `coherent-spark` into `servers{}`. Update `myenvironment` , `mytenant`, and `{token}` then save. ```json { "servers": { "coherent-spark": { "type": "http", "url": "https://mcp.myenvironment.coherent.global/mytenant/mcp", "headers": { "Authorization": "Bearer {token}" } } } } ``` {% endtab %} {% endtabs %} ### Configure for other MCP Clients For other MCP-compatible clients, use the following connection details: | Key | Value | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Transport | `http` | | Server URL |


The {environment} is part of your Log in to Spark URL.
Example:

| | Protocol Version | `2024-11-05` or later | | Authentication |

If using the authorization token, then include the Authorization request header.


Example: Authorization: Bearer eyJhbGciO...

| ## **Use Coherent MCP tools** Once connected to the MCP server, your AI client will have access to the following tools. ### Spark Execute v3 * Name: `spark_execute_v3` * Description: Execute an API call to a Spark service. * Reference: [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md). | Property | Description | | --------------------- | -------------------------------------------------------------------------------------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `revision` | Spark service version number. This identifies the specific service version to use. | | `version_id` | `version_id` of a Spark service version. This identifies the specific service version to use. | | `requestPayload` | Request payload as a JSON object. | | `call_purpose` | Call purpose for tagging the API call. | | `source_system` | Source system for tagging the API call. | | `correlation_id` | Correlation ID for tagging the API call. | | `requested_output` | Comma separated string of output names to keep in the response data. | | `service_category` | Comma separated string of subservices to call. | | `transaction_date` | Transaction date to resolve a version number if `revision` or `version_id` are not provided. | | `debug_solve` | Enable `Xsolve` solver debugging. | | `debug_xcall` | Enable `Xcall` debugging. | | `manual_now` | Epoch time to evaluate current date and time. | | `profile` | Enable performance tracing. Only works for Neuron debug compilation. | | `random_seed` | Random number generation seed. | | `show_max_calc_chain` | When `profile` is enabled, indicate the longest calculation chain in the workbook. | | `top_n_profile` | When `profile` is enabled, lists the sheets, rows, columns, and cells with the longest calculation time. | ### Spark service info * Name: `spark_service_info` * Description: Get information about a Spark service. * Reference: [Get service version](/spark-apis/service-apis/get-service-version.md). | Property | Description | | ------------ | --------------------------------------------------------------------------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `version_id` | `version_id` of a Spark service version. This identifies the specific service version to use. | ### Spark service generate code snippet * Name: `spark_generate_snippet` * Description: Generate a code snippet that can be used to call a Spark service. This is based upon the [npm](https://www.npmjs.com/) package [postman-code-generators](https://www.npmjs.com/package/postman-code-generators). | Property | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `version_id` | `version_id` of a Spark service version. This identifies the specific service version to use. | | `language_code` | Language code for code snippet generation. Commonly used ones include (`curl`, `python`, `java`, `csharp`, `openapi`). If not provided, defaults to `curl`. | | `language_variant` | Language variant for code snippet generation. Commonly used ones include (`cURL`, `http.client`, `python`). If not provided, defaults to the value of `language_code`. | ### List supported snippet languages To get the list of `language_code` and `language_variant`, run the following script.
JavaScript ```javascript var codegen = require('postman-code-generators'), supportedCodegens = codegen.getLanguageList(); var table = supportedCodegens.map(function (lang) { return { key: lang.key, label: lang.label, syntax_mode: lang.syntax_mode, variants: lang.variants.map(function (v) { return v.key; }).join(', ') }; }); console.log('key,label,syntax_mode,variants'); table.forEach(function (row) { console.log([row.key, row.label, row.syntax_mode, '"' + row.variants + '"'].join(',')); }); ```
This is the list of `language_code` and `language_variants`: | language\_code | language\_variant | | -------------- | ---------------------------------------------- | | `curl` | `cURL` | | `dart` | `dio`, `http` | | `go` | `Native` | | `http` | `HTTP` | | `java` | `OkHttp`, `Unirest` | | `javascript` | `Fetch`, `jQuery`, `XHR` | | `kotlin` | `Okhttp` | | `c` | `libcurl` | | `nodejs` | `Axios`, `Native`, `Request`, `Unirest` | | `objective-c` | `NSURLSession` | | `ocaml` | `Cohttp` | | `php` | `cURL`, `Guzzle`, `HTTP_Request2`, `pecl_http` | | `postman-cli` | `Postman CLI` | | `powershell` | `RestMethod` | | `python` | `http.client`, `Requests` | | `r` | `httr`, `RCurl` | | `ruby` | `Net::HTTP` | | `rust` | `reqwest` | | `shell` | `Httpie`, `wget` | | `swift` | `URLSession` | ## Troubleshoot issues | Issue | Cause(s) | Solution(s) | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Error: "Bad Request: Server not initialized" | The server requires initialization before handling requests. |

This should be handled automatically by the MCP client. If you see this error:
1. Ensure you're using an MCP-compatible client.
2. Verify the client sends an initialize request first.
3. Check that the server URL is correct.

| | Error: "No authorization token available" | Missing or invalid authorization token. |

1. Verify your token is included in the Authorization header

2. Ensure the format is Bearer YOUR\_TOKEN (with Bearer prefix).

3. Check that your token has not expired.

4. Obtain a fresh token if needed.

| | Error: "Invalid or expired token" | The JWT token has expired or is invalid. |

1. Obtain a new token.
2. Update your client configuration with the new token.
3. Restart your AI client.

| | Error: "Tenant is not available" | The token doesn't contain tenant information. |

1. Verify your user account has proper tenant assignment.
2. Check with your administrator to ensure proper claims in the JWT
3. Ensure the token contains the required tenant claim.

| | Tools not appearing in AI client |

Possible causes:
1. Server connection failed.
2. Token authentication failed.
3. Client not properly configured.

|

1. Check the client's console/logs for connection errors.
2. Verify the server URL is correct.
3. Ensure Authorization header is properly formatted.
4. Test the token with a direct API call.

| | CORS errors in browser-based clients | Browser security restrictions. |

The server has CORS enabled. If you still see errors:
1. Ensure you're using HTTPS (not HTTP).
2. Check that your client properly sends the Origin header.
3. Verify the server allows your origin.

| If you encounter issues not covered in this guide: 1. Confirm the server status to verify the server is operational. 2. Review logs and check your AI client's console/logs for detailed errors. 3. Contact [Support](/support/faq.md). ## Security best practices 1. Never commit tokens to version control. * Add config files to `.gitignore` . * Use environment variables or secure vaults. 2. Rotate tokens regularly. * Obtain fresh tokens periodically. * Use token refresh mechanisms when available. 3. Use `HTTPS` only. * Never send tokens over unencrypted connections. * Verify the server URL uses `https://` . 4. Limit token scope. * Request only the scopes you need. * Follow principle of least privilege. 5. Monitor token usage. * Review your authentication logs. * Report suspicious activity immediately. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.coherent.global/integrations/model-context-protocol-mcp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.