AI connections for IT and developers

For IT and developers: Taktyl's MCP servers, the OAuth sign-in, the limits, Claude Code, and every tool.

For IT and developers. For the plain guide, see Build with Claude or ChatGPT.

Two servers

	The assistant server	The data server
Address	`/mcp` on your Taktyl address	`/mcp/taktyl`
Sign-in	OAuth 2.1, authorisation code with PKCE (S256 only), scope `mcp:use`	Your organisation's Data API token, as a bearer token
Acts as	The person who chose Allow, in one organisation, with their own permissions	The organisation
Changes	Activities students cannot reach yet (never published, or a copy), and their first Publish, with Allow changes to drafts	Never
Student names	Only with Let this AI see students' names	Never: totals only
Plan	Department or Institution (`taktyl.mcp`)	Department or Institution (`taktyl.data_access`)

The assistant server

Discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. Apps register themselves at /oauth/register; the sign-in may only return to an allowed address (Claude, ChatGPT, Perplexity, Microsoft 365 Copilot, Copilot Studio, Gemini Enterprise, and http://localhost on any port for apps on your own computer).
Tokens last an hour and refresh for 30 days of use.
Who: staff only, asked on the Allow screen, on Allow and on every call. A student, a switched-off account, an organisation that is closed or switched off, a plan without AI assistants, or AI assistants switched off in Organisation › Settings › AI features is refused.
Claude Code: claude mcp add --transport http taktyl https://your-taktyl-address/mcp, then /mcp inside Claude Code to sign in.
Two choices on the Allow screen, both off until ticked: Allow changes to drafts (change drafts and publish) and Let this AI see students' names (each student's results, never an email address). Both are set only on the Allow screen: to change either, the person disconnects and connects again. The person sees each connection's choices on Account › Integrations, and organisation admins see them under Organisation › Integrations › AI connections.
Nothing students can reach: an activity that has ever been published (live, with unpublished changes, or taken down), and any interaction such an activity uses, is refused by every change tool and by publish-activity, with "…is open to students, so the assistant cannot change it". The app works on activities never published, or on a copy made with copy-activity: a new draft that is never published, with its own copies of every interaction, sharing nothing with the original. The person moves the changes over to the live activity in Taktyl.
Publish is the person's own Publish button, for an activity never published (a new one, or a copy), with its checks: a picture with no description, an empty activity or an unfinished interaction stops it; links that may not work are reported in the answer, not a refusal. The version says it was published through the app, the audit log records it, and the person gets a notification.
Limits: 60 request units a minute per person, with daily backstops; 300 changes an hour per person, counted only when a change lands; 30 publishes an hour per person. The same call five times with nothing changing between is refused, and five refusals in a row pause the connection for 15 minutes. Lists come in pages of 25, at most 100. Every reply on a connection that may change things ends with a usage line.
Unknown arguments are refused, not ignored.
Logged: every call (tool, outcome, arguments, and for a change the state before it), and every change in the organisation's audit log as made by the person through the app.
Never: take an activity down, delete, mark, grade, write feedback to a student, write a student's answers, give an extension, set the dates of an activity that has been published, touch an LMS placement or gradebook, or manage people. A page or a question taken out of a draft is restorable. Student totals from fewer than 5 students are withheld, with names allowed or not.

Tools: reading

Tool	What it does
`about-connection`	Who it acts for, what it may do, the limits left, and the organisation's own words
`list-workspaces`	The workspaces the person works in
`search-content`	Activities and interactions by title
`list-folders`	The person's folders in a workspace
`list-activities`	Activities the person may open, in pages
`get-activity`	One activity whole: pages, settings, dates, scoring, LMS placements (read only), what stops Publish
`list-interactions`	The person's interactions in a workspace
`get-interaction`	One interaction's whole document, with the right answers
`list-interaction-types`	Every type and quiz question kind, with the fields each takes
`list-themes`	The themes on offer in a workspace
`list-templates`	The templates the person may start from
`list-library-files`	Pictures, videos, sounds and captions files in the library
`list-versions`	An activity's published versions
`check-activity`	What would stop Publish, and accessibility hints
`get-activity-insights`	One activity's student totals, withheld under 5
`get-workspace-insights`	A workspace's year in totals, for its leaders
`organisation-usage`	The plan and its allowances, for organisation admins
`find-activity`	The activity a `source_ref` was given to
`get-activity-results`	Each student's name, attempts, best, latest and counting score, last hand-in and newest answers on one activity; only with Let this AI see students' names, never an email

Tools: changing drafts

Each changes an activity or interaction students cannot reach: an activity never published, or a copy. An activity that has been published, and an interaction one uses, are refused.

Tool	What it does
`create-activity`	A new draft, blank or from a template, with an optional `source_ref`
`copy-activity`	A copy of an activity to work on, also of one students have: never published, with its own copies of every interaction, and an optional new title
`update-activity`	Title, description, cover and finish screens
`create-folder`	One of the person's folders
`move-activity`	Into another folder
`add-content`	Several pages in one call, all or nothing
`add-interaction`	A new interaction page with its whole content
`add-existing-interaction`	Link an interaction from the library
`add-content-page`	A content page with its items
`update-content-page`	A content page's title and items
`update-interaction`	An interaction's title and whole document
`duplicate-interaction`	A copy, also of one a published activity uses
`move-page`	A page to a place
`remove-page`	Take a page out of a draft (restorable)
`restore-page`	Put it back
`add-question`	One quiz question
`update-question`	Change one quiz question
`move-question`	Move one quiz question
`remove-question`	Take one quiz question out (restorable)
`restore-question`	Put it back
`set-question-media`	A library file with a question
`update-page-scoring`	Counts, weight and gated, per page
`update-activity-settings`	Attempts, which score counts, pass mark, when answers show
`apply-theme`	A theme on offer, or the default
`set-availability`	Open and close dates, only before a first publish
`save-as-template`	A copy into the person's or the workspace's templates

Tools: publishing

Tool	What it does
`publish-activity`	Publish an activity that has never been published (a new one, or a copy) as its Publish button does, with the same checks; links that may not work are reported. An activity students already have is the person's to publish again, and there is no tool to take one down

The data server

For reporting tools, on an organisation Data API token made on Organisation › Integrations. Read only, totals only, and each tool needs the token ability its REST twin needs.

Tool	Ability	What it does
`organisation-usage`	`organisation:read`	The plan, its features and usage
`list-workspaces`	`catalogue:read`	The workspaces
`list-activities`	`catalogue:read`	Activities, by workspace or status
`list-interactions`	`catalogue:read`	The interactions one activity runs
`get-activity-insights`	`insights:read`	Student totals per activity, withheld under 5
`get-workspace-insights`	`insights:read`	A workspace's activities in totals