# customplanview MCP server

Read-only [Model Context Protocol](https://modelcontextprotocol.io/) access to **Planview Portfolios Enterprise**, targeting the **August 2026 API version (`2026-08`)**.

The server runs over stdio and is suitable for VS Code, Claude Desktop, and the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).

## Features

- List portfolios with pagination and an optional status filter
- Get a portfolio by ID
- Search portfolios by text
- Forward the configured API version with every request
- Keep the tool surface read-only

## 1. Prerequisites

Install or obtain the following before starting:

- Node.js 20 or newer
- Access to a Planview Portfolios Enterprise tenant
- A bearer token with permission to read portfolio data
- The portfolio API route used by your tenant or API gateway

Check your installations:

```powershell
node --version
npm --version
```

## 2. Install dependencies

From the project directory, run:

```powershell
npm install
```

## 3. Create your environment file

Copy the example file:

```powershell
Copy-Item .env.example .env
```

Open `.env` and set the required values:

```dotenv
PLANVIEW_BASE_URL=https://your-planview-tenant.example.com
PLANVIEW_API_TOKEN=replace-with-your-bearer-token
PLANVIEW_API_VERSION=2026-08
PLANVIEW_PORTFOLIOS_PATH=/api/portfolios
```

Optional scopes can be supplied as a comma-separated list:

```dotenv
PLANVIEW_SCOPES=portfolio.read,portfolio.list
```

### Configuration reference

| Variable | Required | Description |
| --- | --- | --- |
| `PLANVIEW_BASE_URL` | Yes | Base URL for your Planview tenant or API gateway. |
| `PLANVIEW_API_TOKEN` | Yes | Bearer token used for read-only API requests. |
| `PLANVIEW_API_VERSION` | No | API version. Defaults to `2026-08`. |
| `PLANVIEW_PORTFOLIOS_PATH` | No | Portfolio route. Defaults to `/api/portfolios`. |
| `PLANVIEW_SCOPES` | No | Comma-separated scopes sent to the API. |

The default portfolio path is a placeholder convention. Confirm the exact route and authentication requirements in your tenant's Planview August 2026 API documentation before connecting.

## 4. Validate the project

Run the TypeScript check and build the server:

```powershell
npm run check
npm run build
```

Both commands should complete without errors. The compiled server is written to `dist/`.

## 5. Run the server

Run the compiled server:

```powershell
npm start
```

Or run directly from TypeScript during development:

```powershell
npm run dev
```

This is a stdio server. It does not open a web port, and stdout must remain reserved for MCP protocol messages.

## 6. Connect from VS Code

The repository includes `.vscode/mcp.json`.

1. Make sure `.env` contains your tenant URL and token.
2. Open the project in VS Code.
3. Open the MCP view or chat tools panel.
4. Start `planview-portfolios-enterprise`.
5. Ask your MCP client to list, search, or retrieve portfolios.

VS Code starts the server with `npm run dev` and loads variables from the workspace `.env` file.

## Available tools

| Tool | Inputs | Purpose |
| --- | --- | --- |
| `planview_list_portfolios` | `limit`, `offset`, optional `status` | Return a page of portfolios. |
| `planview_get_portfolio` | `portfolioId` | Return one portfolio by identifier. |
| `planview_search_portfolios` | `query`, `limit` | Search portfolios using the tenant's query behavior. |

All tools make `GET` requests. No create, update, or delete operations are exposed.

## Troubleshooting

### `PLANVIEW_BASE_URL is required`

Make sure `.env` exists and contains a valid `PLANVIEW_BASE_URL` value.

### `PLANVIEW_API_TOKEN is required`

Add a valid bearer token to `.env`. Do not commit or share this file.

### `Planview request failed (404 ...)`

Your tenant likely uses a different route. Update `PLANVIEW_PORTFOLIOS_PATH` after confirming the correct August 2026 API path.

### `Planview request failed (401 ...)` or `(403 ...)`

Verify that the token is active, is intended for the configured tenant, and has the required read permissions or scopes.

### No tools appear in the MCP client

Run `npm run build`, confirm that Node.js is version 20 or newer, and restart the MCP client. For protocol-level inspection, run the server through MCP Inspector.

## Security

- `.env` is excluded from Git by `.gitignore`.
- Use a short-lived, least-privilege read token where possible.
- Never place tokens in source code, prompts, issues, or logs.
- Review tenant response shapes and pagination behavior before extending the server.
- Keep new capabilities read-only unless a separate write capability is explicitly reviewed.

## Project layout

```text
src/server.ts                    MCP server and Planview HTTP client
.vscode/mcp.json                 VS Code MCP launch configuration
.env.example                     Environment template
.github/copilot-instructions.md  Project-specific development guidance
```

## Useful commands

```powershell
npm install       # Install dependencies
npm run check     # Type-check without emitting files
npm run build     # Compile to dist/
npm run dev       # Run TypeScript directly
npm start         # Run the compiled server
```

## License

Private application code. Add the license required by your organization before publishing.