# How MCP works in Teamhood

An AI assistant connects to Teamhood through the Model Context Protocol, MCP for short. It acts as the person who connected it. It can do only what that person's role allows, and only in that person's organization.

## What an assistant can do

An assistant works through a fixed set of tools. With them it can:

- Read the item types, their fields and the values each field allows
- Find, read, create, change and delete items, and add or remove the people who watch them
- Link items that depend on each other, and remove those links
- Read, post, edit and delete comments
- Read, log, correct and delete time
- Read an item's history
- Read the images and text files attached to an item
- Read working hours, time off and planned hours
- List the people and teams in the organization
- Create, change and delete item types, fields, their options and teams
- Invite people and withdraw invitations
- Search these help pages

An assistant can change the text only of comments you wrote. It cannot read other attached files, such as PDFs or spreadsheets. When it reads planned hours, it sees only the hours someone planned explicitly, not the hours the app spreads from each task's estimate. A link it adds between items does not reschedule either item.

An assistant has no tools that change roles, views, automations or organization settings. It cannot change the role or teams of someone already in the organization. One exception: a select value the field does not have yet is added as a new option, if your role has **Manage fields & types**.

Deleting an item moves it and everything under it to the trash, where it can be restored for 30 days.

## Changing the organization's setup

The tools that change types, fields, teams and invitations need a connection you approved for setup changes, or a personal token. Your role must also allow the change. Types and fields need **Manage fields & types**. Teams and invitations need **Manage users & teams**.

An assistant cannot remove a select option while items hold it, or limit an option to fewer types while items of the other types hold it. Items in the trash do not count. The assistant must first move those items to another option. Renaming an option keeps it on the items that hold it.

## Read and change, or read only

Teamhood gives every organization two addresses. The **Connection address** offers all of the tools, unless the assistant asks for less. An assistant that signs in also needs your approval for setup changes before it gets the setup tools. The **Read-only address** offers only the tools that read.

When you approve an assistant, Teamhood shows what it asks for. A connection made to the read-only address can never ask for more.

## An example

You ask an assistant connected to the **Connection address** to move TASK-12 to Done. The assistant reads the item types, and learns that Status is a field of tasks and that Done is one of its values. It then changes TASK-12. Everyone viewing the item sees the change at once, and the item's activity shows it under your name with the **AI** label. A comment the assistant posts carries the same label beside your name.

If your role cannot change TASK-12, the assistant is refused just as you would be in the app, and it is told why.

## How long a connection lasts

A connection ends when you disconnect it. The assistant loses access on its next request.

It also stops at once when you are deactivated, or when the organization's subscription lapses, as personal tokens do. It stops too when the organization requires two-factor authentication and you have not set it up.

Resetting your password, changing your email address, or an administrator resetting your two-factor authentication signs out every assistant that connected by signing in. It loses access within the hour, then asks you to sign in again. It also asks if it goes unused for 30 days. These three changes do not affect a personal token.

## How it works

An assistant signs in with OAuth. Each approval covers one organization and one address. Teamhood then gives the assistant an access token that opens that address and nothing else. The access token cannot reach the app itself, so a read-only assistant cannot use it to make changes another way.