> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teamova.net/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Teamova to AI assistants like Claude, ChatGPT, Copilot, and Gemini using the Model Context Protocol

## Overview

Teamova exposes a **MCP Server** (Model Context Protocol) that lets you interact with your Planning Poker data from any AI assistant. Ask questions about your sessions, view results, and create new sessions — all through natural language.

<CardGroup cols={2}>
  <Card title="Multi-platform" icon="robot">
    Works with Claude, ChatGPT, Copilot, Gemini, and any MCP-compatible client.
  </Card>

  <Card title="Secure by design" icon="shield">
    OAuth 2.1 with PKCE — you control which organizations and permissions to
    grant.
  </Card>
</CardGroup>

## Getting started

### Prerequisites

* You have an active Teamova account.
* You are a member of at least one organisation.
* You are using an MCP-compatible AI assistant (Claude, ChatGPT, Copilot, Gemini, etc.).

<Steps>
  <Step title="Find your MCP Server URL">
    Go to **Account > Connections** in Teamova. The MCP Server URL is displayed in the MCP section at the bottom of the page.

    ```url theme={null}
    https://mcp.teamova.net/mcp
    ```
  </Step>

  <Step title="Add to your AI assistant">
    Paste the URL in your AI assistant's MCP settings:

    * **Claude**: Settings > MCP Servers > Add Server
    * **ChatGPT**: Settings > Apps > Add MCP Server
    * **Copilot**: Copilot Studio > Actions > MCP
    * **Gemini**: Settings > MCP Servers
  </Step>

  <Step title="Authorize access">
    Your AI assistant will redirect you to Teamova's consent screen. Select which organizations to grant access to, review the permissions, and click **Allow**.

    You can select **one or multiple organizations** — the AI assistant will be able to access data from all selected organizations.

    After authorizing, the page will confirm the connection was successful. You can then return to your AI assistant.
  </Step>

  <Step title="Start using">
    Ask your assistant anything about your Planning Poker sessions:

    * "List my organizations"
    * "Show me the results of my last Planning Poker session"
    * "List all active sessions in the Marketing organization"
    * "Create a new Planning Poker session for Sprint 13"
  </Step>
</Steps>

## Available tools

The MCP Server exposes the following tools to AI assistants:

| Tool                          | Type  | Description                                                             |
| ----------------------------- | ----- | ----------------------------------------------------------------------- |
| `teamova_list_organizations`  | Read  | List your authorized organizations with names and IDs                   |
| `teamova_list_sessions`       | Read  | List and filter your Planning Poker sessions with pagination            |
| `teamova_get_session`         | Read  | Get full session details including participants, stories, and votes     |
| `teamova_get_session_results` | Read  | Aggregated estimation results: consensus, standard deviation, vote time |
| `teamova_create_session`      | Write | Create a new Planning Poker session with guided deck and team selection |
| `teamova_add_stories`         | Write | Add a batch of stories to an existing session                           |

### Filtering by organization

If you have authorized multiple organizations, you can filter sessions by organization:

* "List sessions in my Marketing organization" — the assistant will use `teamova_list_organizations` to find the organization ID, then call `teamova_list_sessions` with the `organization_id` filter.
* If no organization filter is specified, the assistant will return sessions from **all** authorized organizations.

<Note>
  Write tools require the `planning-poker:write` permission. Read tools only
  require `planning-poker:read`.
</Note>

## Permissions

When you connect Teamova, you grant specific permissions (scopes) to the AI assistant:

| Scope                  | What it allows                                |
| ---------------------- | --------------------------------------------- |
| `planning-poker:read`  | View sessions, results, votes, and statistics |
| `planning-poker:write` | Create sessions and add stories               |
| `team:read`            | View team information and members             |
| `organization:read`    | List your authorized organizations            |

You can revoke access at any time from **Account > Connections**.

## Multi-organization support

Teamova supports authorizing AI assistants across multiple organizations:

* **During consent**, select one or more organizations using the checkboxes.
* **After authorization**, the AI assistant can access data from all selected organizations.
* **Use "Select all"** to quickly authorize all your organizations.
* **Filter at any time** by asking the assistant to focus on a specific organization.

<Tip>
  If you add a new organization later, you'll need to reconnect your AI assistant to include it.
</Tip>

## Security

* **OAuth 2.1 + PKCE** — Industry-standard authentication with proof key for code exchange
* **Multi-organization access** — Choose exactly which organizations to share during consent
* **Scoped permissions** — AI assistants can only access what you explicitly allow
* **Token expiration** — Access tokens expire after 1 hour; refresh tokens after 30 days
* **Revocation** — Revoke access instantly from your account settings

## Example prompts

Here are some example prompts you can use with your AI assistant once connected:

<AccordionGroup>
  <Accordion title="List your organizations">
    "What organizations do I have access to?"

    The assistant will call `teamova_list_organizations` and show you all authorized workspaces.
  </Accordion>

  <Accordion title="View session results">
    "Show me the results of the Sprint 12 Planning Poker session"

    The assistant will call `teamova_get_session_results` and present consensus estimates, standard deviation, and vote times for each story.
  </Accordion>

  <Accordion title="Filter sessions by organization">
    "List all active sessions in my Marketing organization"

    The assistant will find the organization ID, then call `teamova_list_sessions` with the organization filter.
  </Accordion>

  <Accordion title="Create a session">
    "Create a Planning Poker session called Sprint 13 with Fibonacci deck"

    The assistant will use `teamova_create_session`, ask for confirmation, and create the session.
  </Accordion>

  <Accordion title="Add stories">
    "Add these stories to the Sprint 13 session: User login, Password reset, Profile editing"

    The assistant will call `teamova_add_stories` to batch-add the stories.
  </Accordion>

  <Accordion title="Compare sessions">
    "Compare the estimates from Sprint 11 and Sprint 12"

    The assistant will call `teamova_get_session_results` for both sessions and present a comparison.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication fails">
    Make sure you're logged into Teamova before authorizing the AI assistant. If
    the consent screen doesn't appear, try clearing your browser cookies and
    logging in again.
  </Accordion>

  <Accordion title="No sessions returned">
    The MCP Server only returns sessions from organizations you authorized.
    If you have multiple organizations, make sure you selected the right ones
    during the consent step, or ask the assistant to "list my organizations" to
    verify which are connected.
  </Accordion>

  <Accordion title="Organization names show as IDs">
    If organization names appear as UUIDs instead of names, reconnect your AI
    assistant. Older connections may not have organization names embedded in
    the token.
  </Accordion>

  <Accordion title="Write operations denied">
    Write tools require the `planning-poker:write` scope. If you only granted
    read access, reconnect and select the write permission.
  </Accordion>
</AccordionGroup>