@telora/mcp-products

MCP server that exposes Telora product operations to Claude Code. Tools use a consolidated action-based API — each tool handles multiple actions via an action parameter (e.g., telora_product with action: "list" or action: "create").

Setup

1. Add to your project

Create .mcp.json in your project root, pointing to the local build:

{
  "mcpServers": {
    "telora-products": {
      "command": "node",
      "args": ["mcp/telora-products/dist/index.js"],
      "env": {
        "TELORA_TRACKER_ID": "your-tracker-uuid",
        "TELORA_URL": "http://your-supabase-url:54321",
        "TELORA_MCP_PROFILE": "human"
      }
    }
  }
}

Note: Earlier versions used npx @telora/mcp-products, but npx resolves to a globally installed version which may be outdated. The local build path prevents version drift.

2. Register credentials (once per machine)

Ask your Telora org admin to create an AI tracker for you, then register with the code:

telora-ai register <registration-code>

Alternatively, set environment variables TELORA_TRACKER_ID and TELORA_URL in .mcp.json.

3. Build the MCP server

cd mcp/telora-products && npm run build

4. Restart Claude Code

The tools will be available immediately.

Profiles

The TELORA_MCP_PROFILE environment variable controls which tools are registered:

| Profile | Use case | Behavior | |---------|----------|----------| | human | Interactive Claude Code sessions | Core tools at startup + telora_discover for on-demand loading | | full | Default, all tools | Everything registered at startup | | execution | Daemon strategy execution | Delivery/issue/agent tools, no OKR/ideas/workflows | | factory | Daemon factory execution | Factory + product tools only |

Tool Discovery (Human Profile)

The human profile uses a two-tier loading strategy to stay within Claude Code's deferred tool budget:

Startup tools (always available, 21 decomposed):

• telora_product — 5 actions: list, create, get, update, overview
• telora_product_strategy — 4 actions: list, create, update, reorder
• telora_product_delivery — 6 actions: list, create, update, operationalize, delete, reorder
• telora_product_issue — 4 actions: list, create, update, delete
• telora_discover — 2 actions: list, load

Deferred domains (loaded on demand via telora_discover):

| Domain | Tools | Actions | Why deferred | |--------|-------|---------|--------------| | agent | telora_agent | 5 | Escalations are infrequent in interactive sessions | | context | telora_product_context, telora_product_context_link | 7 | Context doc management is occasional setup work | | connector | telora_connector_start | 1 | Daemon launch is a one-time operation | | factory | telora_factory_blueprint_list, telora_factory_spec, telora_factory_instance | 8 | Factory workflows are a separate domain | | okr | telora_objective, telora_key_result, telora_strategy_key_result | 10 | Goal-setting is periodic, not daily | | ideas | telora_idea, telora_idea_connection, telora_idea_cluster | 12 | Brainstorming is a distinct activity | | workflows | telora_workflow | 5 | Workflow config is admin setup | | playbooks | telora_playbook | 4 | Template usage is infrequent | | profiles | telora_deployment_profile | 5 | CI/CD config is setup work |

Total after full discover: 78 decomposed tools (within the 80 budget).

Using telora_discover

# List all domains with their tool indexes (shows what's available before loading)
telora_discover(action: "list")

# Load a specific domain
telora_discover(action: "load", domain: "factory")

# Load everything at once
telora_discover(action: "load", domain: "all")

The list action returns a toolIndex per domain — tool names, summaries, available actions, and keywords — so you can decide which domain to load without guessing.

Available Tools

Product Management

| Tool | Actions | Description | |------|---------|-------------| | telora_product | list, create, get, update, overview | Product registry: manage software products and their settings |

Strategy Management

| Tool | Actions | Description | |------|---------|-------------| | telora_product_strategy | list, create, update, reorder | Execution roadmap: group deliveries into themed work scopes |

Delivery Management

| Tool | Actions | Description | |------|---------|-------------| | telora_product_delivery | list, create, update, operationalize, delete, reorder | Work packages: shippable increments with acceptance criteria |

Issue Tracking

| Tool | Actions | Description | |------|---------|-------------| | telora_product_issue | list, create, update, delete | Task tracking: issues, bugs, and context groups within deliveries |

Agent & Escalation

| Tool | Actions | Description | |------|---------|-------------| | telora_agent | role_list, escalate, escalation_list, escalation_get, escalation_update | AI agent roles and human-AI escalation requests |

Context Documents

| Tool | Actions | Description | |------|---------|-------------| | telora_product_context | list, create, update, delete, reorder | Knowledge base: product context documents for AI agents | | telora_product_context_link | link, unlink | Attach/detach context documents to strategies or deliveries |

Factory

| Tool | Actions | Description | |------|---------|-------------| | telora_factory_blueprint_list | (no action param) | List factory blueprints with gate configs and resource limits | | telora_factory_spec | create, get, list, update, validate | Define what to build via conversational spec authoring | | telora_factory_instance | get, update | View and control running factory instances (pause, cancel) |

OKR Management

| Tool | Actions | Description | |------|---------|-------------| | telora_objective | create, get, list, update | Strategic objectives with cascading alignment | | telora_key_result | create, list, update, delete | Measurable targets with metric types and confidence levels | | telora_strategy_key_result | link, unlink | Connect strategies to key results for traceability |

Idea Cloud

| Tool | Actions | Description | |------|---------|-------------| | telora_idea | create, list, update, delete | Capture ideas: observations, hypotheses, references | | telora_idea_connection | create, list, update, delete | Map relationships between ideas (supports, causes, contradicts) | | telora_idea_cluster | create, list, update, delete | Group related ideas into clusters |

Workflows

| Tool | Actions | Description | |------|---------|-------------| | telora_workflow | list, get, create, update, assign | Configure lifecycle stages, transition guards, and assignments |

Playbooks

| Tool | Actions | Description | |------|---------|-------------| | telora_playbook | list, get, create, instantiate | Template strategies with pre-configured deliveries and issues |

Deployment Profiles

| Tool | Actions | Description | |------|---------|-------------| | telora_deployment_profile | create, list, get, update, link_to_product | Define target environments and deployment guidelines |

Connector

| Tool | Actions | Description | |------|---------|-------------| | telora_connector_start | (no action param) | Launch Telora daemon for autonomous agent execution |

Usage

Just ask Claude Code naturally:

• "Show me my products in Telora"
• "Create a new strategy called 'Q1 Launch' for my product"
• "List all issues for the current delivery"
• "Create a P0 bug under delivery X"

Common Workflows

Create a product with strategy and delivery

1. telora_product(action: "create", name: "My App")
2. telora_product_strategy(action: "create", productId: "<id>", name: "MVP Launch")
3. telora_product_delivery(action: "create", productId: "<id>", name: "Core Features", strategyId: "<id>")
4. telora_product_issue(action: "create", deliveryId: "<id>", title: "Build login page", issueType: "Task")

Track work on issues

1. telora_product_issue(action: "list", deliveryId: "<id>")
2. telora_product_issue(action: "update", issueId: "<id>", status: "In Progress")
3. telora_product_issue(action: "update", issueId: "<id>", status: "Done")

Set up OKRs linked to strategy

1. telora_objective(action: "create", title: "Increase user retention")
2. telora_key_result(action: "create", objectiveId: "<id>", title: "Reduce churn to 5%", targetValue: 5, unit: "%")
3. telora_strategy_key_result(action: "link", strategyId: "<id>", keyResultId: "<id>")

Load a playbook

1. telora_playbook(action: "list")
2. telora_playbook(action: "get", playbookId: "<id>")
3. telora_playbook(action: "instantiate", playbookId: "<id>", productId: "<id>")

Manage context documents

1. telora_product_context(action: "create", productId: "<id>", title: "Architecture Guide", content: "...", includeMode: "always")
2. telora_product_context_link(action: "link", documentId: "<id>", entityType: "strategy", entityId: "<id>")
3. telora_product_context(action: "list", productId: "<id>", strategyId: "<id>")

Assign a workflow to a delivery

1. telora_workflow(action: "list", entityType: "delivery")
2. telora_workflow(action: "assign", workflowId: "<id>", entityType: "delivery", entityId: "<id>")
3. telora_workflow(action: "get", workflowId: "<id>")

Build an idea cloud

1. telora_idea(action: "create", productId: "<id>", content: "Users want faster onboarding", sourceType: "observation")
2. telora_idea(action: "create", productId: "<id>", content: "Reduce sign-up steps to 2", sourceType: "hypothesis")
3. telora_idea_connection(action: "create", sourceIdeaId: "<id1>", targetIdeaId: "<id2>", connectionType: "supports")
4. telora_idea_cluster(action: "create", productId: "<id>", name: "Onboarding", centerIdeaIds: ["<id1>", "<id2>"])

Error Handling

All tools return errors in a consistent format. Common errors:

| Error | Cause | Resolution | |-------|-------|------------| | "Invalid access token" | Tracker ID expired or invalid | Regenerate tracker ID in Telora UI | | "Rate limit exceeded" | Too many requests | Wait and retry | | "Not found" | Resource doesn't exist | Check the ID | | "Insufficient permissions" | User lacks access to the org unit | Request access from admin |

Credential Sources

Credentials are loaded in this order (first found wins):

1. Environment variables: TELORA_TRACKER_ID and TELORA_URL
2. telora-ai database: ~/.syntelyos/ai_tracking.db (created by telora-ai register)

Legacy TELORA_ACCESS_TOKEN is still supported but deprecated. Use TELORA_TRACKER_ID (UUID) instead.

Authentication Details

The MCP server authenticates to the Telora product-api edge function using a Profile Tracker ID. This is a UUID associated with your user profile.

To get your Tracker ID:

1. Go to Telora > Settings > AI Work Trackers
2. Click "Generate Tracker ID" on your profile
3. Copy the UUID

Tracker expiry: Tracker IDs expire after 90 days of inactivity. Each successful API call auto-refreshes the expiry.

See Authentication Guide for full details.