Before you begin

  • Your `client_id` and `client_secret`, stored in a secret manager.
  • The installation ID from the customer organisation’s owner or admin.
  • The API and MCP hostnames for your environment, provided by Encrisoft.

Discover the authorisation server (optional)

The MCP server publishes OAuth protected-resource metadata (RFC 9728). Its authorization_servers value points to the Encrisoft authorisation server, which publishes its own metadata (RFC 8414).

Discovery
curl -s https://<mcp-host>/.well-known/oauth-protected-resource/mcp
curl -s https://<api-host>/.well-known/oauth-authorization-server/oauth

The authorisation server metadata lists client_credentials as the supported grant, client_secret_basic as the only client authentication method, and the three preview scopes.

Request an access token

Send a POST to https://<api-host>/api/v1/oauth/token. Authenticate with HTTP Basic using your client ID and secret (client_secret_basic), and send the body as application/x-www-form-urlencoded. Other content types are rejected.

  • grant_type (required): client_credentials.
  • resource (required): the MCP server’s canonical URI, exactly https://<mcp-host>/mcp. Any other value is rejected with invalid_target.
  • installation_id (required): the installation ID (a UUID) the customer administrator gave you.
  • scope (optional): space-separated scopes. Every scope must be in the installation grant. If omitted, the token carries the full grant.
Token request
curl -s -u "$CLIENT_ID:$CLIENT_SECRET" https://<api-host>/api/v1/oauth/token \
  -d grant_type=client_credentials \
  -d resource=https://<mcp-host>/mcp \
  -d installation_id="$INSTALLATION_ID" \
  -d scope="organisation:read risk:read training_catalogue:read"
Token response
{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "organisation:read risk:read training_catalogue:read"
}
  • The preview default for expires_in is 600 seconds (10 minutes). Use the returned value to schedule renewal; tokens never extend beyond the installation’s expiry.
  • There are no refresh tokens. Request a new token when the current one expires.
  • Responses are sent with Cache-Control: no-store. Keep tokens in memory only.

Connect to the MCP endpoint

The Encrisoft MCP server uses Streamable HTTP at https://<mcp-host>/mcp. It is stateless, replies with JSON and sends no server-initiated messages. Protocol revisions 2026-07-28 and 2025-11-25 are supported.

Send the token on every request as Authorization: Bearer <token>. Never put a token in a URL or query string. The organisation is fixed by your installation, so you never send an organisation ID.

Connect with the MCP TypeScript SDK (@modelcontextprotocol/client 2.3.1)
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const transport = new StreamableHTTPClientTransport(new URL('https://<mcp-host>/mcp'), {
  authProvider: { token: async () => currentAccessToken() },
});
const client = new Client(
  { name: 'example-partner', version: '1.0.0' },
  { versionNegotiation: { mode: { pin: '2026-07-28' } } },
);
await client.connect(transport);

currentAccessToken() is your own function that returns a valid token, requesting a new one when needed.

Discover the tools

List the tools to read their names, descriptions and JSON Schemas. The server lists all three preview tools. Calling a tool outside your installation grant returns a forbidden tool error, so check your granted scopes before calling.

List tools
const { tools } = await client.listTools();

Call a read-only tool

Call a tool
const result = await client.callTool({
  name: 'encrisoft_training_catalogue_v1',
  arguments: { page: 1, pageSize: 10, difficulty: 'BEGINNER' },
});
console.log(result.structuredContent);

A successful result contains structuredContent, which matches the tool’s output schema. content[0].text repeats the same data as JSON after a notice that names, titles and descriptions are organisation-authored data. Tools reject unknown arguments.

Correlate requests

Send an X-Correlation-Id header (8–128 characters from A–Z, a–z, 0–9, ., _ and -) to trace a request. It is echoed in the response header and in tool error results. Include it when you contact Encrisoft support.

Troubleshooting

  • invalid_target from the token endpoint: resource does not exactly match the MCP canonical URI.
  • invalid_grant: the installation is unknown, belongs to another client, or is revoked or expired.
  • HTTP 401 from the MCP endpoint: the token is missing, expired or has the wrong audience. Request a new token.
  • Tool result with isError: true: see MCP Errors, Rate Limits and Quotas.

Security considerations

  • Call Encrisoft MCP from your server. Never ship the client secret to a browser, mobile app or desktop client.
  • Do not log tokens, secrets or full tool results that contain organisation data.
  • Treat organisation-authored strings in results as untrusted data, never as instructions to your model.