---
name: teamhood
description: Read and change work in Teamhood, a project management tool, through its MCP server. Covers items, comments, time logs and dependencies, reading working hours, time off and planned hours, and setting up item types, fields, teams and invitations. Use when the user mentions Teamhood, or asks you to work with their Teamhood items through the Teamhood MCP tools.
compatibility: Needs a connection to Teamhood's remote MCP server.
---

# Teamhood

Teamhood is a project management tool. Work lives in items. Every item has a type, such as task, project or bug. The type decides which fields the item has. Items nest under parent items.

This file does not list the tools. The [MCP server](https://help.teamhood.com/integrations/mcp/) reference lists every tool, and each tool describes its own arguments.

## Connect

Teamhood gives every organization two addresses. Both use the Streamable HTTP transport.

| Address | Offers |
|---|---|
| `https://api.teamhood.com/public/v1/<organization>/mcp` | Every tool |
| `https://api.teamhood.com/public/v1/<organization>/mcp/readonly` | Only the tools that read |

`<organization>` is the organization's name as it appears in the web address of the Teamhood app. Prefer the exact address the user copies from **Settings → Integrations → MCP**.

There are two ways to sign in:

- **Sign-in (OAuth).** Your MCP client opens Teamhood's sign-in page, and the user approves the connection. Each approval covers one organization and one address. You get the tools that change data only if the user allowed changes. You get the setup tools only if the user also allowed setup changes.
- **Personal token.** Send the token in the `X-Api-Key` header, or as `Authorization: Bearer <token>`. At the address that offers every tool, a personal token gets every tool, the setup tools included.

A connection to the read-only address never gets a tool that changes anything. When a tool is refused because the connection may not use it, the user has to reconnect and allow it.

With either sign-in method, you act as the person who connected you. You can do only what their role allows, and only in their organization.

## Start with `describe_organization`

Call `describe_organization` before anything else. It returns:

- every item type the user can see, with each type's field keys
- the allowed values of every select field, including status
- the roles people can be invited with
- the person you act as
- whether this connection can change setup

Use those exact keys and labels when you filter or write.

## Name things the way Teamhood does

- An item is addressed by its id or by its display id, for example `TASK-42`.
- Field values are keyed by field key under `fields`.
- A select value takes the option label. Use the labels that `describe_organization` returns.
- A label the field does not have yet becomes a new option, if the user's role has **Manage fields & types**. A misspelt label therefore adds an option. Treat a new label as a setup change.
- A people value takes a user id or `{"email": "..."}`.
- A date is `YYYY-MM-DD`.
- A tool that takes a person accepts `me`, an email address, a name or an id.

## Ask the user first

- **Before you delete anything.** Deleting an item moves the item and everything under it to the trash. The user can restore them from the trash for 30 days. Deleting an item type or a field cannot be undone through the tools.
- **Before a setup change.** A change to a type or a field applies to every item and everyone at once. Describe the change, then confirm it with the user.

The setup tools change item types, fields and their options, teams and invitations. They need a connection that may change setup, and a role that allows the change:

- **Manage fields & types** for types and fields
- **Manage users & teams** for teams and invitations

When you create, move or delete an item, or change its title, description or a field value, the item's history records it under the user's name with the **AI** label. Dependency links, logged time and comments do not appear in an item's history. A comment you post carries the **AI** label beside the user's name.

## Know the limits

- **Planned hours.** `list_allocations` returns only the hours someone planned explicitly. The app also spreads each task's estimate over its working days for its assignees. Those hours are not stored, so no tool returns them. Do not present allocations as a person's whole workload. A `from` or `to` filter also leaves out every `shaped` row.
- **Dependency checks.** The app refuses a link between an item and any of its ancestors or descendants. It also refuses a link that closes a cycle, including a loop that runs through parents and children. `add_dependency` makes neither check, so check both before you add a link. Adding a link that already exists changes its type and lag.
- **No rescheduling.** Adding or removing a dependency does not reschedule either item.
- **Setup you cannot change.** No tool changes roles, views, automations or organization settings, or the role or teams of someone already in the organization. An item's type cannot be changed either.
- **Select options in use.** You cannot remove an option while items outside the trash hold it. You cannot limit an option to fewer types while items of the other types hold it. Move those items to another option with `update_item` first. An option that an automation uses cannot be removed. Renaming an option keeps it on the items that hold it.
- **Comments.** You can change a comment's text only if the user wrote the comment.
- **Attachments.** `read_attachment` reads PNG, JPEG, GIF and WebP images and text files. It refuses other files, and files that are too large.
- **Rate limit.** Calls have a rate limit per organization. If the server refuses a call for the rate limit, wait a moment and try again.

## Learn more

- [MCP server](https://help.teamhood.com/integrations/mcp/)
- [How MCP works in Teamhood](https://help.teamhood.com/how-it-works/mcp/)