Build a custom client

Use the client credentials flow to connect a custom AI client or agent to Mindtickle MCP without interactive sign-in. Requests still run on behalf of the Mindtickle user identified by username in the token request.

For an organization-managed connection through an AI client’s settings, see Set up the connector. To connect your account to an existing connector, see Connect your account.

Note

Client-credentials setup is not self-service. The Mindtickle team issues the credentials for this flow. Contact your Customer Success Manager (CSM) or account team to set up this integration. User-authorized clients follow the separate OAuth registration flow described in Step 2.

Before you begin

Confirm the following:

• You can request client credentials from your Mindtickle Customer Success Manager or account team, as described in Step 1.
• You know your Mindtickle instance URL (referred to as {mindtickle-instance-url} throughout this article). Use only the hostname, without the protocol or path. For example, example.mindtickle.com.
• Your AI client supports MCP over HTTP and can send the Authorization header with every request. Clients such as Claude Desktop and Cursor support MCP natively. Platforms such as Slack, Salesforce Agentforce, and Microsoft 365 Copilot require a custom integration.

Step 1: Get your client credentials

Contact your Customer Success Manager or account team to obtain the following credentials:

• client_id
• client_secret

Note

• The client_secret is required to generate access tokens. Store it in a secure vault or secret manager. Never expose it in code, logs, or shared documents.
• Credentials for the client credentials grant are issued only by Mindtickle. There is no self-service API for obtaining these credentials.

Scopes

A scope grants access to one or more tools. Include one or more scopes, separated by spaces, in the scope parameter when requesting a token. The server checks the token’s scopes before invoking any tool and returns only matching tools from tools/list. For what each tool does, see Supported tools.

Scope	Grants access to	Description
read:search	mindtickle_search	Lets the client call the search tool.
read:copilot_chat	mindtickle_seller_copilot_ask	Lets the client call the Copilot chat tool.
read:rooms	find_deals, find_companies, find_contacts, find_rooms, fetch_room	Lets the client call the read-only Digital Sales Room tools.
write:rooms	create_room, edit_room, share_room, create_contacts	Lets the client call the Digital Sales Room tools that create or modify data, including sharing a room with a buyer.

Note

Follow the principle of least privilege. Request only the specific scopes your integration needs.

Step 2: Generate an access token

Choose the authentication flow for your integration:

• Unattended requests: Use the client credentials grant below. Supply username to identify the Mindtickle user whose permissions apply to tool calls. This flow does not require interactive sign-in for each token request.
• User-authorized requests: If each user signs in and authorizes access, use the authorization code grant with Proof Key for Code Exchange (PKCE) and dynamic client registration. The AI client handles registration as part of this flow; it is separate from obtaining client credentials from Mindtickle. See Set up the connector for the connection flow and Best practices for registration requirements.

For the client credentials flow, send the following request to obtain a short-lived Bearer token.

Endpoint

POST https://{mindtickle-instance-url}/api/users/v1/oauth/token

Request headers

Content-Type: application/json

Request

Parameter	Type	Required	Description
grant_type	string	Required	The OAuth grant type. Set this to client_credentials.
client_id	string	Required	The client ID issued by Mindtickle.
client_secret	string	Required	The client secret issued by Mindtickle.
username	string	Required	The email address of the Mindtickle user on whose behalf the token is issued. Tool calls run in this user’s context, and results respect the permissions and content access policies applied to that user inside Mindtickle.
scope	string	Required	The scopes required for the request, separated by spaces. For example, read:search read:copilot_chat. See Scopes.

Request example

{
  "grant_type": "client_credentials",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "username": "user@example.com",
  "scope": "read:search read:copilot_chat"
}

Response

Parameter	Type	Description
access_token	string	The JWT used to authenticate requests to the Mindtickle MCP server.
token_type	string	The token type. The value is always Bearer.
expires_in	number	The token’s validity period, in seconds.
scope	string	The scopes granted for this token.

Response example

This illustrative response uses a placeholder token. Use the returned expires_in value rather than assuming the example duration.

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:search read:copilot_chat"
}

Token lifecycle

• Use the expires_in value to determine how long a token remains valid. Do not hardcode a token duration.
• Cache and reuse the token, and obtain a replacement before it expires, rather than requesting a new token on every call.
• When a token expires, call the token endpoint again to generate a new one before making further requests. The server does not refresh tokens automatically for the client credentials grant.
• The token endpoint allows 20 requests per minute per client. Requests above this limit return 429. Reuse valid tokens to avoid unnecessary token requests.

Step 3: Configure your client

Configure your AI client to connect to the Mindtickle MCP server using the access token generated in the previous step. Include the token in the Authorization header in the format Bearer <access_token> on every request.

Server URL:

https://{mindtickle-instance-url}/mcp

Example client configuration:

The following example shows a Cursor-style mcp.json configuration. Replace MINDTICKLE_MCP_URL with the complete HTTPS server URL shown above, including /mcp, and ACCESS_TOKEN with your access token. These are placeholders, not environment-variable interpolation syntax. Adapt the structure and secure credential loading to your client’s configuration format.

{
  "mcpServers": {
    "mindtickle": {
      "url": "MINDTICKLE_MCP_URL",
      "headers": {
        "Authorization": "Bearer ACCESS_TOKEN"
      }
    }
  }
}

Note

• The Mindtickle MCP server requires authentication on every request.
• Restart or refresh your client after updating the configuration.
• Store tokens in environment variables or a secure secret manager. Do not hardcode tokens in your client configuration.

Step 4: Discover and call tools

Once your client is connected, it can discover the tools available on the Mindtickle MCP server using the tools/list method. The tools returned depend on the scopes included in your access token. The server validates the token and enforces scope on every request.

The Mindtickle MCP server exposes several tools. For the full list, required scopes, and behavior details, see Supported tools.

End-user interaction guidance

End users typically ask task-based questions rather than platform-specific ones. For example:

• “Find learning content to understand product XYZ.”
• “Learn more about product XYZ.”
• “Find the battle card for competitor ABC.”
• “Identify training for objection handling for product XYZ.”

Integrator responsibilities

• Configure your agent or copilot to map user intent to the appropriate tool.
• Do not depend on users explicitly referencing Mindtickle in their queries.
• Use explicit tool references only for manual or developer testing. Do not require explicit tool names in production user experiences.

Example: a single tool call

The following example shows the method and parameters for a tools/call request that resolves a company by name. The tool-call examples in this section are request fragments, not complete JSON-RPC envelopes.

{
  "method": "tools/call",
  "params": {
    "name": "find_companies",
    "arguments": {
      "query": "Acme Corp"
    }
  }
}

The response contains matching company records. Pass a selected company ID in the company_ids parameter of find_deals. The find_rooms tool supports a free-text query, not a company ID filter. For exact request and response schemas, see Supported tools.

Example: chaining tool calls

A workflow can use the result of one tool call as input to the next. This example finds a company, finds its matching deals, and retrieves a room using the room_id returned by find_deals:

{
  "method": "tools/call",
  "params": {
    "name": "find_companies",
    "arguments": {
      "query": "Acme Corp"
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "find_deals",
    "arguments": {
      "company_ids": ["{id from find_companies}"]
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "fetch_room",
    "arguments": {
      "room_id": "{room_id from find_deals}"
    }
  }
}

Select the intended company and deal if a call returns multiple matches. Pass the selected deal’s non-null room_id to fetch_room. If no deal matches or its room_id is null, this sequence has no room UUID to retrieve. Do not pass a company ID or deal ID as a room ID.

The find_rooms tool supports a free-text query, not company_id or deal_id filters. This sequence therefore uses find_deals to obtain the room UUID directly. See Supported tools for field details.

Conversation history

For the mindtickle_seller_copilot_ask tool, your client must maintain the full conversation history, including all follow-up questions, and send the updated history with each request.

Request example

{
  "input": [
    { "role": "user", "content": "How do I improve readiness?" },
    { "role": "assistant", "content": "Start with coaching and role-play..." },
    { "role": "user", "content": "Create a 2-week plan." }
  ]
}

For full conversation handling rules, see Supported tools.

Streaming responses

By default, mindtickle_seller_copilot_ask returns a single buffered response once Seller Copilot has finished generating it. To receive the response incrementally instead, include a progressToken in the request’s _meta field. When a token is present, the server sends a series of MCP notifications/progress messages as each chunk of the answer becomes available, in addition to the final buffered response.

Note

Use incremental notifications/progress messages to display progress; their delivery is not guaranteed. Treat the final tools/call response as authoritative, but check its status and error before treating fullText as complete. A stalled response stream can return a partial answer. Streaming is opt-in and specific to this tool; no other Mindtickle MCP tool supports it.

Errors

This section documents the errors returned by the token endpoint and by the Mindtickle MCP server itself.

Token endpoint status codes

Status	Description
200	The request is successful and returns a valid response.
400	The request is invalid or missing required parameters.
401	The request contains invalid client credentials.
403	The user is not authorized to perform this request.
429	The client exceeded 20 token requests per minute.

MCP error codes

The Mindtickle MCP server returns the following error codes on tools/list and tools/call requests.

Code	Description
MISSING_AUTH_HEADER	The request does not include the Authorization header.
INVALID_AUTH_HEADER	The Authorization header is not in the correct format.
TOKEN_EXPIRED	The token has expired and must be regenerated.
TOKEN_INVALID	The token is invalid or cannot be verified.
INVALID_TOKEN	The token is missing required claims or cannot be validated.
TOKEN_VALIDATION_ERROR	The system encountered an error while validating the token.
INVALID_CONTEXT_TOKEN	The token was rejected during context validation.
INSUFFICIENT_SCOPE	The token does not include the scope required for the tool being called.
NO_TOKEN_FOUND	The Authorization header did not contain a valid token.
CLIENT_CANCELLED	The client canceled the request.
API_ERROR	A downstream Mindtickle API failed.
VALIDATION_ERROR	Request validation failed.
INTERNAL_ERROR	An unexpected system error occurred.

Downstream API errors

These errors come from the Mindtickle APIs called by a tool. They appear inside the tool response rather than as token or MCP-level errors.

Code	Description
API_AUTH_FAILED	The Mindtickle API the tool called rejected the request because the underlying token has expired or is no longer valid.
API_PERMISSION_DENIED	The Mindtickle API the tool called rejected the request because the user does not have permission to perform it.
API_TIMEOUT	The request reached the Mindtickle API, but no response came back before the tool’s timeout. See Supported tools for per-tool timeout values.
GRAPHQL_ERROR	The Mindtickle API returned a response that also contains one or more errors, most commonly from the search tool.
COPILOT_BACKEND_ERROR	Seller Copilot reported a failure while generating a response to a mindtickle_seller_copilot_ask call.

Failure behavior

Situation	Behavior
tools/list failure	The request fails with an MCP error.
tools/call failure	The system returns an error in the tool response.
Upstream API failure	The error appears in the tool output.

Note

• Token-related issues are the most common cause of failures. Always validate scopes and token freshness before retrying a failed request.
• Some errors appear inside tool responses rather than as HTTP errors. Inspect both the HTTP status and the response body when debugging.
• If your MCP session expires mid-conversation, the server recovers automatically on the next tool call. You do not need to detect this and reconnect yourself.

For security, reliability, and integration-design practices to follow when building against this path, see Best practices.

Related

• Supported tools: Tool parameters, response fields, and limits.
• Best practices: Security, reliability, and integration guidance.
• Set up the connector: The managed connector setup path.