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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.