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).
curl -s https://<mcp-host>/.well-known/oauth-protected-resource/mcp
curl -s https://<api-host>/.well-known/oauth-authorization-server/oauthThe 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, exactlyhttps://<mcp-host>/mcp. Any other value is rejected withinvalid_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.
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"{
"access_token": "eyJ…",
"token_type": "Bearer",
"expires_in": 600,
"scope": "organisation:read risk:read training_catalogue:read"
}- The preview default for
expires_inis 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.
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.
const { tools } = await client.listTools();Call a read-only 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_targetfrom the token endpoint:resourcedoes not exactly match the MCP canonical URI.invalid_grant: the installation is unknown, belongs to another client, or is revoked or expired.- HTTP
401from 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.

