> For the complete documentation index, see [llms.txt](https://docs.coherent.global/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coherent.global/integrations/model-context-protocol-mcp.md). # 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 and updates may be made from release to release. 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 for [connectors](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities#h_b7263f8086). * Name: `coherent-spark` (can be customized). * 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" %} The name `coherent-spark` can be customized. 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" %} The name `coherent-spark` can be customized. 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{}`. The name `coherent-spark` can be customized. 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", "type": "streamableHttp" } } } ``` {% 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{}`. The name `coherent-spark` can be customized. Update `myenvironment`, `mytenant`, and `{token}` then save. ```json { "mcpServers": { "coherent-spark": { "url": "https://mcp.myenvironment.coherent.global/mcp", "type": "streamableHttp", "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{}`. The name `coherent-spark` can be customized. 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{}`. The name `coherent-spark` can be customized. 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. | | `version_id` | `version_id` of Spark service version. Identifies specific service version. | | `requestPayload` | Request payload as JSON object. | | `call_purpose` | Call purpose for tagging API call. | | `source_system` | Source system for tagging API call. | | `correlation_id` | Correlation ID for tagging API call. | | `service_category` | Comma separated string of subservices to invoke. | | `transaction_date` | Transaction date to resolve a version number if `revision` or `version_id` are not provided. | ### Spark service info * Name: `spark_service_info` * Description: Get information about a Spark service. * Reference: [Get service version](/spark-apis/service-apis/retrieve-latest-version.md). | Property | Description | | ------------ | --------------------------------------------------------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `version_id` | `version_id` of Spark service version. Identifies specific service version. | ### Spark service generate code snippet * Name: `spark_generate_snippet` * Description: Generate code to call Spark service Execute API using [`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.

Common values: "curl", "javascript", "python".

Default: "curl".

| | `language_variant` |

Language variant for code snippet generation.

| #### 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` | ### [Testing Center](/navigation/testing-center.md) tools #### Spark service download testbed template * Name: `spark_download_testbed_template` * Description: For Testing Center. Testbeds contain data to run on Spark service. Download Excel testbed template for Spark service to add testbed. | Property | Description | | ------------ | -------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | #### Spark download testbed result * Name: `spark_download_testbed_result` * Description: For Testing Center. Testbed results contain calculated results after testbed run on Spark service. Download completed testbed result. | Property | Description | | ------------------- | -------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `testbed` \* | Testbed name. | | `testbed_result` \* | Testbed result name. | #### Spark list testbeds Name: `spark_list_testbeds` Description: For Testing Center. Testbeds contain data to run on Spark service. List testbeds for Spark service. | Property | Description | | ------------ | -------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `testbed` \* | Testbed name. | #### Spark list testbed results Name: `spark_list_testbed_results` Description: For Testing Center. Testbed results contain calculated results after testbed run on Spark service. List testbed results for Spark service testbed. | Property | Description | | ------------------------ | ----------------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `testbed` \* | Testbed name. | | `testbed_result_name` \* | Testing Center testbed result name. | #### Spark run testbed Name: `spark_run_testbed` Description: For Testing Center. Testbeds contain data to run on Spark service. Start testbed run on Spark service. | Property | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `revision` | Spark service version number. | | `version_id` | `version_id` of Spark service version. Identifies specific service version. | | `service_category` | Comma separated string of subservices to invoke. | | `testbed` \* | Testbed name. | | `testbed_result` |

Testbed result name.

Default "Spark\_1.0.0\_\" UTC.

| | `testbed_result_description` | Testbed result description. | | `testbed_list_max_pages` | Maximum pages to search for testbed name. Default `10`. | #### Spark run status testbed Name: `spark_run_status_testbed` Description: For Testing Center. Check status of Spark testbed run started via `spark_run_testbed`. Default `poll_interval_seconds` `5` up to default `100` `max_iterations` until run reaches terminal status. If still in progress after `max_iterations` results make this tool call again or check in Spark application. | Property | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | | `run_id` \* | `run_id` returned by `spark_run_testbed`. | | `wait_for_complete` | Poll until terminal status or `max_iterations`. When `false`, perform a single status check. Default `true`. | | `poll_interval_seconds` | Seconds between status polls. Ignored when `wait_for_completion` is `false`. Default `5`. | | `max_iterations` | Maximum poll iterations before returning the in-progress snapshot. Default `100`. | | `folder` | Spark service folder name to render summary table. | | `service` | Spark service name to render summary table. | | `testbed` \* | Testbed name to render summary table and download hint. | | `revision` | Spark service version number. | | `version_id` | `version_id` of Spark service version. Identifies specific service version. | | `service_category` | Comma separated string of subservices to invoke. | | `testbed_result` |

Testbed result name.

Default "Spark\_1.0.0\_\" UTC.

| | `testbed_result_description` | Testbed result description. | | `testbed_list_max_pages` | Maximum pages to search for testbed name. Default `10`. | #### Spark compare testbed results Name: `spark_compare_testbed_results` Description: For Testing Center. Testbed results contain calculated results after testbed run on Spark service. Compare testbed results for Spark service testbed. | Property | Description | | --------------------- | --------------------------------- | | `folder` \* | Spark service folder name. | | `service` \* | Spark service name. | | `testbed` \* | Testbed name. | | `testbed_result_1` \* | Testbed result name (base). | | `testbed_result_2` \* | Testing result name (comparison). | ## 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.