Panaya Server

A TypeScript-based Model Context Protocol (MCP) server that exposes Panaya REST APIs as MCP tools. It is designed to run over stdio, so it can be connected to Claude Desktop and other MCP-compatible clients.

The server discovers a fixed set of Panaya entities, registers one grouped MCP tool per entity, calls the Panaya REST API with X-Auth-Token, and returns responses in both Claude-readable text and machine-readable structuredContent.

Features

• Runs as a local MCP server over stdio.
• Connects to Panaya REST APIs using PANAYA_BASE_URL, PANAYA_USERNAME, and PANAYA_TOKEN.
• Generates a short-lived Panaya API token through POST /api/accesstoken and sends that generated token as X-Auth-Token.
• Registers tools for common Panaya entities:
  • projects
  • requirements
  • tests
  • defects
  • releases
  • cycles
  • businessProcesses
• Provides a unified action-based tool for each entity.
• Supports list, get, create, update, delete, and search actions.
• Includes an API operation registry tool, panaya_operations, that can discover, describe, and call documented Panaya REST operations by operationId.
• Returns REST responses as formatted JSON text for Claude.
• Also returns structured JSON through MCP structuredContent.
• Writes server logs to stderr, keeping stdout clean for MCP protocol messages.
• Loads .env from the project root even when launched by Claude from another working directory.

Project Structure

src/
  client/
    panayaClient.ts       # Panaya REST client
  config/
    env.ts                # Environment loading and validation
  discovery/
    apiDiscovery.ts       # Entity discovery and metadata lookup
  generator/
    schemaBuilder.ts      # Metadata schema helper retained for future typed schemas
    toolGenerator.ts      # Registers grouped MCP tools for each entity
  generated/
    panayaOperations.ts   # Generated API operation registry
  runtime/
    bootstrap.ts          # Discovers entities and registers tools
  index.ts                # stdio MCP server entry point
  logger.ts               # stderr logger for Claude MCP logs
  server.ts               # MCP server factory

Prerequisites

• Node.js 20 or newer is recommended.
• npm
• A valid Panaya API token.
• Claude Desktop, if you want to connect this server to Claude.

Setup

Install dependencies:

npm.cmd install

Create a local .env file from the example:

Copy-Item .env.example .env

Edit .env:

PANAYA_BASE_URL=https://your-panaya-host.example.com
[email protected]
PANAYA_TOKEN=your_long_lived_panaya_access_token_here

PANAYA_TOKEN should be the long-lived access token used by Panaya's /api/accesstoken endpoint. The MCP server exchanges it for a generated API token and uses the generated token in X-Auth-Token.

Do not commit .env. It contains credentials and is ignored by Git.

Build the TypeScript project:

npm.cmd run build

Running Locally

Start the compiled MCP server:

npm.cmd start

This server is intended for MCP stdio clients. When run directly in a terminal, it will wait for MCP JSON-RPC messages on stdin.

Claude Desktop Configuration

Open your Claude Desktop config file:

C:\Users\sonal_sharma\AppData\Roaming\Claude\claude_desktop_config.json

Add this server inside the existing mcpServers object:

{
  "mcpServers": {
    "panaya-mcp-sonal": {
      "command": "node",
      "args": [
        "C:\\Users\\sonal_sharma\\panaya-mcp-sonal\\dist\\index.js"
      ],
      "cwd": "C:\\Users\\sonal_sharma\\panaya-mcp-sonal"
    }
  }
}

If you already have other MCP servers configured, keep them and add only the panaya-mcp-sonal entry.

After editing the config:

1. Run npm.cmd run build.
2. Fully restart Claude Desktop.
3. Ask Claude to use the Panaya MCP server, for example:

Use the Panaya MCP server to list projects.

Available Tools

For each entity, the server registers one grouped tool:

panaya_<entity>

Current tools:

panaya_projects
panaya_requirements
panaya_tests
panaya_defects
panaya_releases
panaya_cycles
panaya_businessProcesses

The server also registers this operation registry tool:

panaya_auth
panaya_operations

Use panaya_auth with { "action": "refresh" } if a long Claude session needs to force-refresh the generated Panaya API token before continuing.

panaya_operations is generated from the official Panaya Postman collection. The current generated registry contains 146 curated API examples from Shared Panaya Catalog of API examples.postman_collection.json. Swagger can still be used as a fallback source if the Postman collection is unavailable.

Each tool accepts this input shape:

{
  "action": "list",
  "id": "optional-id",
  "operationId": "optional-operation-id",
  "projectId": "optional-project-id",
  "pathParams": {},
  "queryParams": {},
  "data": {},
  "query": {}
}

Only action is required. Valid actions are:

list
get
create
update
delete
search
operation

Action field requirements:

Action	Required fields	REST call
list	none	GET /api/v1/<entity>
list with project filter	projectId	GET /api/v1/<entity>?projectId=<projectId>
get	id	GET /api/v1/<entity>/<id>
create	data	POST /api/v1/<entity>
update	id, data	PUT /api/v1/<entity>/<id>
delete	id	DELETE /api/v1/<entity>/<id>
search	query	POST /api/v1/<entity>/search
operation	operationId, plus required pathParams, queryParams, and data	Calls the matching documented operation

Tool Examples

List all projects:

{
  "action": "list"
}

List requirements for a project:

{
  "action": "list",
  "projectId": "19051"
}

Get one project:

{
  "action": "get",
  "id": "19051"
}

Search an entity:

{
  "action": "search",
  "query": {
    "status": "ACTIVE"
  }
}

Create an entity:

{
  "action": "create",
  "data": {
    "name": "Example"
  }
}

Update an entity:

{
  "action": "update",
  "id": "19051",
  "data": {
    "name": "Updated Example"
  }
}

Delete an entity:

{
  "action": "delete",
  "id": "19051"
}

Call a documented operation from a grouped entity tool:

{
  "action": "operation",
  "operationId": "Create_Defect",
  "pathParams": {
    "projectId": "19051"
  },
  "data": {
    "name": "Example defect"
  }
}

Operation Registry Tool

Use panaya_operations to discover, describe, or call documented REST operations that do not fit the simple grouped entity actions.

List operations:

{
  "action": "list",
  "search": "defect",
  "limit": 10
}

Filter by operation tag/folder:

{
  "action": "list",
  "tag": "Defects",
  "limit": 25
}

Describe one operation:

{
  "action": "describe",
  "operationId": "Create_Defect"
}

Call one operation:

{
  "action": "call",
  "operationId": "Get_All_Defects",
  "pathParams": {
    "projectId": "19051"
  },
  "queryParams": {
    "pageSize": 50,
    "pageNumber": 1
  }
}

Call one paginated page:

{
  "action": "call",
  "operationId": "Get_All_Defects",
  "pathParams": {
    "projectId": "19051"
  },
  "queryParams": {
    "pageSize": 100,
    "pageNumber": 1
  }
}

Fetch all pages for APIs that use pageNumber and pageSize:

{
  "action": "call",
  "operationId": "Get_All_Defects",
  "pathParams": {
    "projectId": "19051"
  },
  "pagination": {
    "all": true,
    "pageSize": 100,
    "maxPages": 20
  }
}

For APIs that use different parameter names, override them:

{
  "action": "call",
  "operationId": "Some_Paginated_Operation",
  "pathParams": {
    "projectId": "19051"
  },
  "pagination": {
    "all": true,
    "pageParam": "page",
    "pageSizeParam": "size",
    "startPage": 0,
    "pageSize": 100,
    "maxPages": 20
  }
}

For operations with a request body, include data:

{
  "action": "call",
  "operationId": "Create_Defect",
  "pathParams": {
    "projectId": "19051"
  },
  "data": {
    "name": "Example"
  }
}

Auth Tool

Force-refresh the generated Panaya API token:

{
  "action": "refresh"
}

Response Format

Tool responses include a text block for Claude:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"projectId\":123,\"projectName\":\"Example\"}]"
    }
  ]
}

They also include structured JSON for MCP clients that support it:

{
  "structuredContent": {
    "data": [
      {
        "projectId": 123,
        "projectName": "Example"
      }
    ]
  }
}

Array responses are wrapped as { "data": [...] } because MCP structuredContent must be an object.

Logging

Logs are written to stderr, which Claude Desktop shows in the MCP server logs. This keeps stdout reserved for MCP protocol traffic.

Example log lines:

[panaya-mcp-sonal] 2026-07-05T11:09:42.590Z tool:start {"name":"panaya_projects","action":"list"}
[panaya-mcp-sonal] 2026-07-05T11:09:42.590Z GET {"path":"/api/v1/projects"}
[panaya-mcp-sonal] 2026-07-05T11:09:42.658Z tool:success {"name":"panaya_projects","action":"list","resultType":"array","count":11}

The logger intentionally avoids printing tokens, headers, or request bodies.

Security Notes

• Never commit .env.
• Keep PANAYA_TOKEN private.
• Keep PANAYA_USERNAME private if it identifies a real user account.
• Rotate the token immediately if it is accidentally shared.
• Review any create, update, or delete tool usage before allowing Claude or another MCP client to call it.
• Avoid logging request bodies if they may contain sensitive business data.
• Keep node_modules/ and dist/ out of Git; rebuild from source after cloning.

Development Commands

Build:

npm.cmd run build

Run compiled server:

npm.cmd start

Run TypeScript source directly:

npm.cmd run dev

Regenerate the operation registry from the official Panaya Postman collection:

npm.cmd run generate:operations:postman -- "C:\Users\sonal_sharma\Desktop\Shared Panaya Catalog of API examples.postman_collection.json"
npm.cmd run build

If only Swagger metadata is available, regenerate from Swagger instead:

npm.cmd run generate:operations:swagger -- C:\Users\sonal_sharma\Desktop\Panaya_Swagger.json
npm.cmd run build

Note: On some Windows systems, PowerShell blocks npm.ps1. Use npm.cmd if you see an execution policy error.

Troubleshooting

Claude Shows Invalid URL

This usually means PANAYA_BASE_URL was not loaded. Confirm that .env exists in the project root and contains:

PANAYA_BASE_URL=https://your-panaya-host.example.com
[email protected]
PANAYA_TOKEN=your_long_lived_panaya_access_token_here

Then rebuild and restart Claude Desktop.

Panaya Returns 401

Check that PANAYA_USERNAME and PANAYA_TOKEN are valid for the configured Panaya host. The server first calls:

POST /api/accesstoken

Then it sends the generated token using:

X-Auth-Token: <token>

For long-running Claude sessions, call panaya_auth with { "action": "refresh" } and then retry the failed request.

Claude Does Not Show the Server

Check that:

• npm.cmd run build completed successfully.
• dist/index.js exists.
• claude_desktop_config.json points to the correct absolute path.
• Claude Desktop was fully restarted after config changes.

Logs Do Not Appear

Claude only captures MCP server logs from stderr. This project logs with console.error() through src/logger.ts.

Git Hygiene

This repository includes a .gitignore that excludes:

• .env and other secret files
• node_modules/
• dist/
• logs and temporary files
• local IDE/tool state

Before pushing to GitHub, verify that secrets are not staged:

git status

Only commit source, configuration templates, lockfiles, and documentation.