Model Context Protocol (MCP)

This feature will continue to be developed and improved over time. 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.

• Authorization token: This server uses OAuth 2.1 authentication with Keycloak, requiring a valid JWT token for all requests. This can be retrieved from the User menu. Currently for long running jobs, this will need to be refreshed manually and the MCP configuration updated. This will be enhanced in future updates.

• MCP-compatible AI client: e.g. Claude Desktop, Cline for Visual Studio Code, Visual Studio, 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. The currently available tools allow for:

• Calling of Spark services, reference Execute API (v3).

• Retrieve a summary of information about the workbook.

• Access detailed information about the details about the Spark service and also generate a code snippet for integration for the language of your choice.

Some detailed instructions are provided below for specific AI clients. If your client is not on the list, review the documentation for your AI client's MCP configuration and use the details below to configure the client.

Configure for Claude Desktop

This requires Node.js 22 to be installed.

The Claude desktop apps bring Claude's capabilities directly to your computer, allowing for seamless integration with your workflow.

1. Claude Desktop supports MCP servers via its configuration file.

2. Open the configuration file appropriate for your operating system.

   1. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json .

   2. Windows: %APPDATA%\Claude\claude_desktop_config.json .

   3. Linux: ~/.config/Claude/claude_desktop_config.json .

3. If you do not have any MCP servers configured, add the following snippet into the document and save. If you already have other MCP servers defined, add coherent-spark into mcpServers.

   {
     "mcpServers": {
       "coherent-spark": {
         "command": "npx",
         "args": [
           "mcp-remote@latest",
           "--http",
           "https://mcp.myenvironment.coherent.global/mcp",
           "--header",
           "Authorization: Bearer {token}"
         ]
       }
     }
   }

4. Update myenvironment and {token}.

5. Save the file.

6. Restart Claude Desktop. Coherent Spark tools should appear in the available tools list.

Configure for Cline

Cline is an extension for Visual Studio Code that supports MCP servers.

1. Install the Cline VS Code extension.

2. Open Cline settings (Settings → Extensions → Cline).

3. In the MCP Servers, click Edit in settings.json.

4. If you do not have any MCP servers configured, add the following snippet into the document and save. If you already have other MCP servers defined, add coherent-spark into cline.mcpServers.

   {
     "mcpServers": {
       "coherent-spark": {
         "url": "https://mcp.myenvironment.coherent.global/coherent/mcp",
         "type": "streamableHttp",
         "headers": {
           "Authorization": "Bearer {token}"
         }
       }
     }
   }

5. Update myenvironment and {token}.

6. Save the file.

7. Restart Visual Studio Code.

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.

1. Open Cursor Settings, Tools & MCP.

2. Click New MCP Server.

3. If you do not have any MCP servers configured, add the following snippet into the document and save. If you already have other MCP servers defined, add coherent-spark into mcpServers.

   {
     "mcpServers": {
       "coherent-spark": {
         "url": "https://mcp.myenvironment.coherent.global/mcp",
         "headers": {
           "Authorization": "Bearer {token}"
         }
       }
     }
   }

4. Update myenvironment and {token}.

5. Save the file.

6. Restart Cursor.

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.

1. Open the Command Palette (F1).

2. Select the command MCP: Open User Configuration.

3. If you do not have any MCP servers configured, add the following snippet into the document and save. If you already have other MCP servers defined, add coherent-spark into servers.

   {
     "servers": {
       "coherent-spark": {
         "type": "http",
         "url": "https://mcp.myenvironment.coherent.global/mcp",
         "headers": {
           "Authorization": "Bearer {token}"
         }
       }
     }
   }

4. Update myenvironment and {token}.

5. Save the file.

6. Restart Visual Studio Code.

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/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	This should be a Bearer token in 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. The documentation describes the technical details related to the tool call, however these can also be invoked through conversation with a LLM.

Call Execute API (v3) with spark_execute_v3

Execute Coherent Spark services using Execute API (v3) with enhanced folder support.

Key	Value
folder	(required) Service folder name.
service	(required) Service name.
inputs	(required) Input data, reference the request_data.
version_id	(optional) Reference to the service version.
subservices	(opotional) Subservices to call.
call_purpose	(optional) Call purpose metadata.

Sample request

{
  "folder": "myfolder",
  "service": "myservice",
  "inputs": {
    "value1": 100,
    "value2": 200
  }
}

Fetch workbook information

Retrieve comprehensive workbook information by SHA-256 hash or workbook ID.

Key	Value
sha256	(optional) SHA-256 hash of the workbook.
workbook_id	(optional) ID of the workbook.

Sample request

{
  "sha256": "a1b2c3d4e5f6..."
}

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.

MCP server direct API call sample request

This can be used to test the token and access to the MCP server. Remember to update myenvironment and {{BEARER_TOKEN}}.

curl --location 'https://mcp.myenvironment.coherent.global/mcp' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json, text/event-stream' \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

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.

Resources

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

GitHub - modelcontextprotocol/typescript-sdk: The official TypeScript SDK for Model Context Protocol servers and clientsGitHub

https://claude.ai/desktopclaude.ai

OAuth 2.1oauth.net