# 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](/support/articles/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 |