Magif.ai Logo

Trust Center

Connector & Integration Technical Specification

How the Magif MCP connector works, what each tool can do, and the current status of API and LMS integration.

Last updated: Version 1.0 - 21 September 2026

Download PDF

Overview

Magif exposes a Model Context Protocol (MCP) connector so a customer can build and manage their own agents from an MCP client such as ChatGPT. This specification documents the connector exactly as implemented today, and the current status of broader API and LMS integration. Where a capability does not exist, it is stated as Not currently supported rather than omitted.

Legacy architecture note: LLM_ANONYMISER is no longer part of the current architecture. Core inference was moved to open-source models hosted on Scaleway in Europe.

Section A: ChatGPT / MCP connector

Endpoint

Path
/api/connector/mcp
Transport
Streamable HTTP, stateless, JSON-RPC 2.0
Protocol version
2025-06-18
Server identity
magify-connector, version 1.0.0
Methods
JSON-RPC methods: initialize, tools/list, tools/call, ping. The endpoint is client-agnostic and works with any MCP client.
Note
The base URL is the customer-facing Magif application host. An unauthenticated request returns 401 with a WWW-Authenticate header so the client can discover the OAuth configuration automatically.

Authentication

OAuth 2.1 with PKCE (S256 recommended). Clients are public (no client secret). The access token is a signed bearer token (JWT).

  1. Register: the client performs dynamic client registration and receives a client_id. Public client, no secret.
  2. Authorize: the user grants consent; Magif issues a short-lived, single-use authorization code (5 minutes) bound to the PKCE challenge.
  3. Token: the client exchanges the code (with the PKCE verifier) for an access token and a refresh token.

Discovery: OAuth configuration is published at the standard discovery endpoints (/.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server).

Token lifetimes: Access token lifetime is 90 days and the refresh token lifetime is 180 days by default (configurable). Access is isolated per connector account.

Scopes: One scope is defined and used: connector. There is no finer-grained scope model. Access control is enforced by per-account isolation (each token maps to a single account) and by paid-feature gating, not by scopes.

Tools

The connector exposes 19 tools. Read tools return information; write tools change the customer's own workspace. No tool can read end-user conversation transcripts, and no tool can read information about other accounts. Three tools are advertised but not yet functional (marked below).

whoami

Read

Read the connector's own account: id, status, agent count, token balance.

link_my_account

Read

Return the account claim link or linked email.

pair_account

Write

Link the connector workspace to a Magif account using a pairing code.

magifai_instructions

Read

Return static reference text. No database or account access.

create_agent

Write (create)

Create an agent, with an auto trial offer and an auto image.

list_my_agents

Read

List the connector's own agents with their chat URLs.

get_agent

Read

Read the configuration of one of the connector's own agents.

set_agent_prompt

Write (modify)

Update an agent's name, description, prompt, intro and token limit.

set_agent_steps

Write (modify)

Replace an agent's structured steps.

add_knowledge

Write (ingest knowledge)

Ingest a knowledge-base document (text, markdown or URL); it is chunked, embedded and indexed.

set_agent_style

Write (modify)

Set chat appearance: colour, greeting, hook, examples, position, radius, tone.

set_agent_image

Write (modify)

Set an agent's profile or cover image from a URL.

generate_image

Write (modify)

Generate an image and set it as the agent profile or cover. Spends account tokens.

create_offer

Write (create, pricing) - paid

Create an offer and set its price and token budget.

update_offer

Write (modify, pricing, publish/unpublish) - paid

Change price, billing, offer type or the active toggle. Activating an offer makes access sellable; deactivating removes it.

delete_agent

Write (delete) - paid

Permanently delete an agent with its offers, steps, knowledge and data.

run_automated_test

Write - paid

Persona test. Advertised but currently a non-functional placeholder.

generate_kb_from_web_research

Write (ingest) - paid

Web research into a knowledge base. Advertised but currently a non-functional placeholder.

get_analytics

Read (analytics) - paid

Usage and conversion analytics. Advertised but currently a non-functional placeholder; no data is returned.

Capability summary

Create agents
Yes (create_agent).
Modify agents
Yes (set_agent_prompt, set_agent_steps, set_agent_style, set_agent_image, generate_image).
Publish / unpublish
Yes, indirectly. Activating an offer makes access sellable; deactivating it removes access (create_offer, update_offer).
Delete
Yes (delete_agent, paid). This permanently deletes the agent and its data.
Change pricing
Yes (create_offer, update_offer, paid): price, token budget, billing frequency and trial parameters.
Ingest knowledge
Yes (add_knowledge). generate_kb_from_web_research is advertised but not yet functional.
Access conversations
No. No connector tool reads end-user or client conversation content.
Access user information
Only the connector's own account (whoami, link_my_account). No lookup of other users or end users.
Access analytics
Not currently available. The get_analytics tool is advertised but returns no data yet.

Conversation data and payloads

What Magif receives
Magif receives only the tool name and the structured arguments the MCP client chooses to send, plus the caller's User-Agent. Magif does not receive the surrounding ChatGPT or other client conversation transcript.
What is stored
Each connector tool call is logged to an internal record (the ConnectorToolCall collection) for operational and support purposes. The record holds the tool name, the arguments (with secret-looking values redacted and a size cap), a short result summary, timing and account status.
Where
Primary database, in the European Union, alongside other platform records.
Retention
An automatic expiry for these tool-call logs is not currently configured in code. A defined retention window for connector tool-call logs is an open item (see the Trust Center confirmation list).
Who can access
Access to the stored tool-call records is restricted to Magif superadministrators, precisely because the arguments can contain personal data. No connector tool can read these records back.

Section B: API / LMS integration capability matrix

Current status of broader API and LMS integration. Where a capability does not exist it is stated explicitly.

API reference availability

Partial

The MCP connector (Section A) is the current programmatic interface, with a documented tool catalogue. A separate general-purpose REST API reference is Not currently available.

Authentication

Available

OAuth 2.1 with PKCE and bearer tokens, for the MCP connector (Section A).

Rate limits

Partial

Pairing attempts are rate-limited and paid features are gated. Published per-tool rate limits are Not currently available.

User provisioning

Not currently supported

The connector provisions its own workspace account. Bulk or directory-based user provisioning (for example SCIM) is Not currently supported.

Roles and permissions

Not currently supported

Access is per-account isolation plus paid gating under a single connector scope. A fine-grained roles and permissions API is Not currently supported.

SSO

Not currently supported

Learner-level data read / export

Not currently available

The connector cannot read end-user conversations, and the analytics tool is not yet functional. Learner-level export is Not currently available.

Conversation count (per learner)

Not currently available

Conversation duration

Not currently available

Agent / topic per learner

Not currently available

The connector exposes the customer's own agent configuration, not per-learner activity.

Assessment / check result

Not currently available

Webhooks

Not currently supported

Polling

Not currently available

There is no learner-data polling endpoint.

Expected event latency

Not applicable

No event stream is exposed today.

Available event payloads

Not applicable

No event payloads are exposed today.

xAPI

Not currently supported

LTI 1.3

Not currently supported

Grade passback

Not currently supported

Export formats

Not currently available

No structured learner-data export is offered today.

Audit logs

Partial

Connector tool calls are logged internally and are accessible to Magif superadministrators. A customer-facing audit-log export is Not currently available.

Moodle integration

Not currently supported

Other LMS integration experience

Not applicable

There is no prior LMS integration deployment to report.