# MCP server

Teamhood runs a remote server for the Model Context Protocol, MCP for short. An assistant connected to it works as the person whose sign-in or personal token it uses. Your organization's exact addresses are in **Settings → Integrations → MCP**.

## Addresses

| 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 your organization's name as it appears in your Teamhood address. Both addresses use the Streamable HTTP transport.

## Signing in

| Method | How |
|---|---|
| Sign-in | The assistant opens Teamhood's sign-in page and asks you to approve it |
| Personal token | Send the token in the `X-Api-Key` header, or as `Authorization: Bearer <token>` |

## Adding it to an assistant

| Assistant | How |
|---|---|
| Claude Code | Run `claude mcp add --transport http teamhood <address>`, then `claude mcp login teamhood` |
| Cursor | In `.cursor/mcp.json`: `{"mcpServers": {"teamhood": {"url": "<address>"}}}` |
| VS Code | In `.vscode/mcp.json`: `{"servers": {"teamhood": {"type": "http", "url": "<address>"}}}` |
| Claude, ChatGPT and others | Add a custom connector or a remote MCP server with the address |

## Tools

A tool marked as changing data is not offered at the read-only address. The organization setup tools are offered to a personal token, and to a connection you approved for setup changes. Every tool runs with your role's permissions.

### Items

| Tool | Does | Changes data |
|---|---|---|
| `describe_organization` | Lists the item types, their fields and select values, the roles, and who you are | |
| `search_items` | Finds items by type, text, parent, field values or last change | |
| `get_item` | Reads one item with its description and fields | |
| `get_item_history` | Reads an item's change history | |
| `create_item` | Creates an item | yes |
| `update_item` | Changes an item's title, fields, description, parent or watchers | yes |
| `delete_item` | Moves an item and everything under it to the trash | yes |
| `add_dependency` | Makes an item depend on another | yes |
| `remove_dependency` | Removes a dependency | yes |

### Comments and time

| Tool | Does | Changes data |
|---|---|---|
| `list_comments` | Reads an item's comments | |
| `add_comment` | Posts a comment | yes |
| `update_comment` | Changes a comment's text or completed mark | yes |
| `delete_comment` | Deletes a comment | yes |
| `list_time_logs` | Reads the time logged on an item | |
| `log_time` | Logs time on an item | yes |
| `update_time_log` | Corrects a time log | yes |
| `delete_time_log` | Deletes a time log | yes |

### People and workload

| Tool | Does | Changes data |
|---|---|---|
| `list_people` | Lists the organization's members and teams | |
| `list_invites` | Lists the invitations nobody has accepted | |
| `get_capacity` | Reads contracted weekly hours | |
| `list_time_off` | Reads time off and reduced hours | |
| `list_allocations` | Reads explicitly planned hours | |

### Organization setup

| Tool | Does | Changes data |
|---|---|---|
| `create_type` | Creates an item type | yes |
| `update_type` | Changes a type's name, key, colour, child types or how it opens | yes |
| `delete_type` | Deletes a type, and its items when you confirm | yes |
| `create_field` | Creates a field with its options | yes |
| `update_field` | Changes a field, and adds, changes or removes its options | yes |
| `delete_field` | Deletes a field | yes |
| `create_team` | Creates a team | yes |
| `update_team` | Renames, recolours or moves a team | yes |
| `delete_team` | Deletes a team | yes |
| `invite_people` | Invites people by email, optionally with their first and last names, with a role and teams | yes |
| `revoke_invite` | Withdraws an invitation | yes |

### Files and help

| Tool | Does | Changes data |
|---|---|---|
| `list_attachments` | Lists an item's files | |
| `read_attachment` | Reads an image or a text file | |
| `search_help` | Searches these help pages | |

## Limits

- An assistant cannot change roles, views, automations or organization settings.
- It cannot change the role or teams of someone already in the organization.
- It cannot remove a select option that items outside the trash still hold.
- It reads PNG, JPEG, GIF and WebP images and text files, but no other attachments.
- Planned hours leave out the hours the app spreads from each task's estimate.
- A dependency it adds does not reschedule either item.
- Its calls have a rate limit per organization, separate from the API's.

## Next

- [Connect an assistant with MCP](../connect-mcp/)
- [How MCP works in Teamhood](../../how-it-works/mcp/)