Model Context Protocol (MCP)

This feature is only enabled on certain environments and tenants. Please contact Support for more information about this feature.

This feature is a work in progress. Please contact Support if you have any questions or feedback.

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.

What is the Model Context Protocol (MCP)? - Model Context ProtocolModel Context Protocol

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 User menu.

• MCP-compatible AI client: e.g. Claude, Cursor, Visual Studio Code, 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 apps bring Claude's capabilities directly to your computer, allowing for seamless integration with your workflow.

1. Follow the instructions in Custom connectors.

   • 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 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.

User login authentication

Update myenvironment and mytenant then submit.

When trying to access the server, you will be prompted for a Coherent Spark login.

claude mcp add --transport http coherent-spark https://mcp.myenvironment.coherent.global/mytenant/mcp

Authorization token

Configure for Cursor

Cursor is an AI-assisted integrated development environment for Windows, macOS, and Linux. It is a fork of Visual Studio Code with additional AI features. Reference Model Context Protocol (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.

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.

{
  "mcpServers": {
    "coherent-spark": {
      "url": "https://mcp.myenvironment.coherent.global/mytenant/mcp"
    }
  }
}

Authorization token

Configure for Visual Studio Code

Visual Studio Code (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.

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.

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.

{
  "servers": {
    "coherent-spark": {
      "type": "http",
      "url": "https://mcp.myenvironment.coherent.global/mytenant/mcp"
    }
  }
}

Authorization token

Configure for other MCP Clients

For other MCP-compatible clients, use the following connection details:

Key	Value
Transport	http
Server URL	https://mcp.{environment}.coherent.global/{tenant}/mcp The {environment} is part of your Log in to Spark URL. Example: https://mcp.myenvironment.coherent.global/mcp
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).

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.

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 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

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.

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.