Panaya MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Panaya MCP Server list all projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Panaya MCP 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, andPANAYA_TOKEN.Generates a short-lived Panaya API token through
POST /api/accesstokenand sends that generated token asX-Auth-Token.Registers tools for common Panaya entities:
projectsrequirementstestsdefectsreleasescyclesbusinessProcesses
Provides a unified action-based tool for each entity.
Supports
list,get,create,update,delete, andsearchactions.Includes an API operation registry tool,
panaya_operations, that can discover, describe, and call documented Panaya REST operations byoperationId.Returns REST responses as formatted JSON text for Claude.
Also returns structured JSON through MCP
structuredContent.Writes server logs to
stderr, keepingstdoutclean for MCP protocol messages.Loads
.envfrom the project root even when launched by Claude from another working directory.
Related MCP server: plutio-mcp
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 factoryPrerequisites
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 installCreate a local .env file from the example:
Copy-Item .env.example .envEdit .env:
PANAYA_BASE_URL=https://your-panaya-host.example.com
PANAYA_USERNAME=your_panaya_username@example.com
PANAYA_TOKEN=your_long_lived_panaya_access_token_herePANAYA_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 buildRunning Locally
Start the compiled MCP server:
npm.cmd startThis 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.jsonAdd 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:
Run
npm.cmd run build.Fully restart Claude Desktop.
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_businessProcessesThe server also registers this operation registry tool:
panaya_auth
panaya_operationsUse 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
operationAction field requirements:
Action | Required fields | REST call |
| none |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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_TOKENprivate.Keep
PANAYA_USERNAMEprivate 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/anddist/out of Git; rebuild from source after cloning.
Development Commands
Build:
npm.cmd run buildRun compiled server:
npm.cmd startRun TypeScript source directly:
npm.cmd run devRegenerate 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 buildIf 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 buildNote: 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
PANAYA_USERNAME=your_panaya_username@example.com
PANAYA_TOKEN=your_long_lived_panaya_access_token_hereThen 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/accesstokenThen 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 buildcompleted successfully.dist/index.jsexists.claude_desktop_config.jsonpoints 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:
.envand other secret filesnode_modules/dist/logs and temporary files
local IDE/tool state
Before pushing to GitHub, verify that secrets are not staged:
git statusOnly commit source, configuration templates, lockfiles, and documentation.
Available Tools
9 toolspanaya_authB
Refresh the Panaya generated API token
Inputs: action (required).
panaya_businessProcessesD
Unified tool for businessProcesses operations
Inputs: action (required), id, data, query, +5 more.
panaya_cyclesD
Unified tool for cycles operations
Inputs: action (required), id, data, query, +5 more.
panaya_defectsD
Unified tool for defects operations
Inputs: action (required), id, data, query, +5 more.
panaya_operationsC
Discover and execute any Panaya Swagger operation by operationId
Inputs: action (required), tag, data, limit, +5 more.
panaya_projectsD
Unified tool for projects operations
Inputs: action (required), id, data, query, +5 more.
panaya_releasesD
Unified tool for releases operations
Inputs: action (required), id, data, query, +5 more.
panaya_requirementsD
Unified tool for requirements operations
Inputs: action (required), id, data, query, +5 more.
panaya_testsD
Unified tool for tests operations
Inputs: action (required), id, data, query, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The generic panaya_operations tool overlaps with all resource-specific tools, as it can execute any operation. This makes it unclear whether to use a specific tool or the generic one, especially since the 'unified' tools likely wrap similar operations.
Most tools follow a consistent panaya_<resource> pattern with snake_case. However, panaya_businessProcesses uses camelCase, and panaya_operations is not a resource but a catch-all, so it deviates slightly from the naming convention.
With 9 tools, the count is reasonable for a domain-specific server. The inclusion of a generic operations tool alongside resource-specific tools is somewhat redundant but does not make the count inappropriate.
The resource-specific tools cover core entities, and panaya_operations fills any gaps by allowing arbitrary operations. Minor gaps may exist in the specific tools (e.g., no explicit update/delete exposed), but the generic tool provides a workaround.
Maintenance
Related MCP Connectors
Every Canopy public API operation as a tool, run as you after a browser sign-in or on an API key.
Discover, plan and run tools across your connected business systems through one OAuth MCP endpoint
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Read and write NetSuite and run SuiteQL from Claude or ChatGPT. Write tools flagged for approval.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables interaction with QA Studio test management platform directly from Claude, allowing users to manage projects, create test runs, view test results, create test cases, and submit manual test results through natural language.77 npmAGPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables Claude and other MCP clients to interact with Plutio's business platform resources including CRM, projects, invoicing, and more through structured tools.135 npm6MIT
- FlicenseBqualityCmaintenanceEnables Claude to interact with JAMA Cloud (Jama Connect) for project management, including creating, updating, and searching items, managing test plans, and adding comments.153-
- AlicenseBqualityCmaintenanceEnables Claude to interact with HacknPlan project management via the MCP protocol. Provides tools for managing projects, work items, boards, milestones, time logs, design models, and cross-project portfolio views.7511 npmMIT