MCP Client Integration

Last updated: June 2026

This feature needs custom activation. Please contact us if you are interested: project-support@pathmate.app

One major advantage of MCP client integration is that customers can connect their own AI systems and services through standardized MCP-compatible interfaces. This allows sensitive data processing and AI orchestration to remain within the customer's own infrastructure and AI ecosystem.

The platform supports integration with external MCP servers as well as GPT-based services.

This chapter explains how MCP integrations can be used inside coachings using a practical example: generating AI podcasts dynamically during a coaching flow.

The example shown in this documentation uses an MCP service for podcast generation. The MCP integration is implemented using JavaScript snippets inside coaching dialogs and allows:

Calling MCP tools
Sending prompts dynamically
Working with variables
Checking job progress
Downloading generated media
Storing files in variables
Displaying generated media inside the coaching

The same principles can also be used for other MCP-based services.

1. Understanding MCP Conceptually

Conceptually, MCP works like an intelligent translation layer between systems.

Instead of hardcoding every interface contract manually, systems can dynamically describe:

Which functionality they provide
Which parameters they expect
Which formats they support

A simplified conceptual workflow looks like this:

A client asks: > "Hello interface, how do you work and what information do you need?"
The MCP server responds: > "I support these tools and expect these parameters in this format."
The client or LLM can then adapt dynamically: > "Perfect, I can structure my information accordingly."

This creates a flexible communication layer between systems.

In an ideal MCP architecture:

An LLM Client communicates with
An LLM Server
Through standardized MCP interactions

The LLM acts as an intelligent translator between interfaces.

2. Overview

The MCP integration works directly inside coaching dialogs via JavaScript snippets.

Typical workflow:

Send a request to an MCP service
Receive a job ID
Store the job ID in a variable
Check generation progress
Download the generated result
Store the media file in a variable
Display the generated media inside the coaching

3. Example Use Case: AI Podcast Generation

In this example, the coaching dynamically generates a podcast about winter activities.

The user prompt is sent to the MCP server:

Generate a podcast about the season winter and recommended winter activities.

The MCP service processes the request and generates an audio podcast.

4. MCP Architecture Inside the Coaching

The integration is implemented through JavaScript snippets inside coaching dialogs.

The scripts can:

Access variables
Call MCP tools
Handle responses
Download files
Store media references
Display generated media later in the coaching

Because the implementation is script-based, the behavior is highly dynamic and customizable.

To learn more on how to create & implement a script to your coaching, check our Javascript chapter

5. MCP Discovery / Initial Step

To verify MCP compatibility, an initial "list" step can be implemented.

The MCP service explains:

Which tools are available
How the service can be used
Which functionality it provides

The result is returned as JSON and is mainly useful for debugging and development purposes.

6. The `mcp()` Helper

The mcp() helper function is available after loading the pragma:

//+ mcp

Basic Call Structure

const response = mcp(
  serverUrl,    // MCP server URL
  method,       // MCP method, typically 'tools/call' or 'tools/list'
  params,       // Parameters passed to the tool (object)
  requestId,    // Optional request ID string
  options       // Optional: headers, trustAllCerts
)

Parameter	Description
`serverUrl`	MCP server URL
`method`	MCP method (e.g. `tools/call`, `tools/list`)
`params`	Parameters passed to the tool
`requestId`	Optional session/request ID
`options`	Additional options (headers, `trustAllCerts`)

The helper builds a JSON-RPC 2.0 envelope and parses the response. The returned object contains:

Field	Type	Notes
`status`	number	HTTP status code
`success`	boolean	`true` if status 2xx and no MCP error
`result`	object	The `result` member of the JSON-RPC reply
`error`	any	Error member of the reply, or transport error
`response`	object	Full raw response (useful for debugging)
`rawResponseBody`	string	Set on parse failure or HTTP error

Timeouts: The MCP helper uses a 10-second connection timeout and a 30-second read timeout. Design your integrations to complete within these limits.

Using Coaching Variables

MCP calls can directly reference coaching variables in the params object. The variable placeholder is substituted before the script runs:

const response = mcp(
  MCP_SERVER_URL,
  'tools/call',
  {
    name: 'checkJobStatus',
    arguments: {
      jobId: '$jobId'   // coaching variable substituted automatically
    }
  }
)

Custom Headers / Authentication

Custom headers can be attached via the options parameter — useful for API keys, authentication tokens, and tenant identifiers:

const options = {
  headers: {
    'X-API-Key': 'your-api-key'
  },
  trustAllCerts: false
}

const response = mcp(serverUrl, 'tools/call', params, null, options)

File References in MCP Calls

If a parameter value starts with file:<reference>, the file is automatically loaded from the media store and base64-encoded before being sent to the MCP server. This allows passing uploaded images or documents directly to MCP tools without manual encoding.

7. Generating a Podcast

The next step is sending a generation request to the MCP server.

The prompt is sent directly to the MCP service. Example prompt:

Generate a podcast about the season winter, including recommended activities for the season.

MCP Response

The MCP service immediately responds with:

{
  "success": true,
  "jobId": "abc123"
}

The Job ID is parsed from the response and stored in a coaching variable. It is required for all subsequent requests.

8. Checking Job Progress

After starting generation, the coaching can periodically check whether the podcast generation has finished.

The MCP service provides:

Current progress
Completion state
Download URL (when finished)

Example response:

{
  "success": true,
  "progress": 100,
  "status": "completed",
  "downloadUrl": "https://..."
}

9. Downloading Generated Media

Once generation is complete, the audio file can be downloaded automatically using the fetch helper.

Files should be:

Stored in variables
Displayed later in the coaching
Attached to messages or media bubbles

Example:

//+ fetch
const audioResponse = fetch(downloadUrl)
// audioResponse.body will be 'file:' for binary responses

Binary responses (audio, video, image, PDF) are automatically persisted in the media store. The body field then contains file:<reference>, which can be stored directly in a coaching variable.

File lifecycle: Files created during a script run are only kept if their reference appears in the result object. Files that are created but not returned are deleted automatically after the run. If the script throws an error, all created files are cleaned up.

10. Complete Example: Nutrition Analysis via MCP

The following example demonstrates a complete MCP integration for AI-based nutrition analysis. A meal image is sent to an MCP server which performs nutrition estimation using an external AI model.

This example covers: custom MCP server URLs, custom request headers, MCP tool execution, dynamic variable passing, AI model configuration, error handling, and returning structured results.

//+ mcp

const result = {}

const mcpServerUrl = 'https://nutrition-analysis.com/mcp-rpc'

const customOptions = {
  headers: {
    'X-API-Key': 'nutrilens-rocks'
  }
}

const nutritionParams = {
  name: 'estimate_nutrition_content',
  arguments: {
    meal_images: ['$imageURL'],      // coaching variable substituted automatically
    genai_api_key: 'Insert_your_api_key',
    genai_model_id: 'gemini-2.5-pro'
  }
}

try {

  const nutritionResponse = mcp(
    mcpServerUrl,
    'tools/call',
    nutritionParams,
    null,
    customOptions
  )

  if (nutritionResponse.success) {
    result.success = true
    result.content = nutritionResponse.result
  } else {
    result.success = false
    result.error = nutritionResponse.error
  }

} catch (e) {
  result.success = false
  result.error = e.toString()
}

const o = {
  mcpResult: result
}

o

Step-by-Step Explanation

1. Importing MCP Support
//+ mcp enables the mcp() helper inside the snippet. Without this pragma, the function is not available.

2. Preparing the Result Object
const result = {} — a local object to store the success state, response content, and any errors. This makes response handling consistent.

3. Custom Headers / Authentication
API keys and other authentication data are passed via customOptions.headers. The MCP call itself does not expose these in the coaching flow.

4. Dynamic Variable Usage
meal_images: ['$imageURL'] — $imageURL is replaced automatically with the actual coaching variable value. This allows user-uploaded meal images to be processed dynamically.

5. Error Handling
Both MCP-level errors (nutritionResponse.success === false) and unexpected runtime errors (catch (e)) are caught and stored in the result. This prevents coaching crashes caused by failed MCP requests.

6. Returning the Result
mcpResult in the result object o contains the complete MCP response. This variable can then be used in dialogs, conditions, visualizations, or later coaching steps.

11. Using the `llm()` Helper

In addition to MCP calls, snippets can directly call an LLM configured on the intervention using the llm() helper:

//+ llm

const reply = llm(1, 'You are a supportive coach.', 'Summarize: $diaryEntry')

const result = {
  coachReply : reply.message,
  llmOk      : reply.success
}
result

Parameter	Description
`index`	1-based index of the LLM configuration on the intervention (up to 5)
`systemPrompt`	Optional system prompt (pass as second argument before the user prompt)
`prompt`	The user prompt; coaching variables are substituted automatically

The response object contains:

Field	Type	Notes
`success`	boolean	Whether the call succeeded
`message`	string	The plain text response
`error`	string	Set if `success === false`

12. Typical MCP Workflow

A typical MCP workflow inside a coaching looks like this:

Send generation request
Receive Job ID
Store Job ID in variable
Poll job status
Receive download URL
Download generated file
Store file reference in variable
Display generated media in coaching

13. Dynamic Coaching Possibilities

Because MCP integrations are fully scriptable, they can support many dynamic coaching scenarios:

AI podcast generation
Nutrition interpretation
AI-generated summaries
Image generation
Voice synthesis
Personalized recommendations
Dynamic reports
Medical document interpretation
Sentiment analysis

The MCP integration is generic and can be adapted to any external service that exposes an MCP-compatible interface.

14. MCP and GPT Integration

The platform supports both MCP integrations and GPT integrations. The technical handling is very similar:

Send request
Handle response
Store variables
Process results dynamically

This allows combining LLM-based logic with external MCP tools inside coachings.

15. Summary

The MCP integration allows coachings to interact dynamically with external AI services.

Using JavaScript snippets, coachings can:

Call MCP tools with dynamic parameters
Use coaching variables in requests
Handle asynchronous generation workflows
Download and store generated files
Display generated media directly inside dialogs
Call configured LLMs for in-flow AI responses

This enables highly dynamic and personalized coaching experiences powered by external AI services.