# MCP Tools

> MCP tools and prompts on the hosted and npm servers — register, parse_cas, enrich, run_skill, and more.

MCP tool reference, code samples, and example workflows.

## Available MCP tools

There are two servers: the hosted server at `https://api.portfoliointel.co.in/mcp`, and the `@portfoliointel/mcp-server` stdio package, which calls the same API. They expose slightly different tools. The stdio package is not yet published to npm, so connect to the hosted server, directly or through `npx -y mcp-remote https://api.portfoliointel.co.in/mcp` for clients that only run stdio servers.

| Tool | Hosted | npm | Description |
| --- | --- | --- | --- |
| `register` | — | Yes | Get a free test key without signing up. Calls [`POST /api/v1/register`](https://docs.portfoliointel.co.in/api-reference/register). Hosted clients get a key from the [OAuth consent page](https://docs.portfoliointel.co.in/mcp/authentication) instead. |
| `parse_cas` | Yes | Yes | Parse a CAS PDF and return structured holdings and metadata. Accepts `pdf_url`, `pdf_base64` or `session_id`, plus `pdf_path` for a local file in the npm package. |
| `enrich` | Yes | Yes | Add returns and benchmark overlays to holdings. |
| `request_upload_url` | Yes | Yes | Create a browser-upload session when the agent can't pass the file itself. |
| `list_skills` | Yes | Yes | List available analysis skills. Needs no scope. |
| `run_skill` | Yes | Yes | Run an analysis skill against a parsed snapshot. Returns flagged holdings with severity, reasoning and a not-advice disclaimer. |
| `generate_report` | Yes | — | Export a snapshot as JSON or CSV. |
| `compare_snapshots` | Not yet | — | Compare two snapshots for allocation drift and value change. Not listed by either server; a direct call returns `501 NOT_IMPLEMENTED`. |

## Prompts

Both servers also expose prompts: ready-made workflows that clients such as Claude Desktop show as slash commands. Clients that only support tools, including the Claude.ai web connector and ChatGPT, don't show them.

| Prompt | Arguments | What it does |
| --- | --- | --- |
| `analyze_my_portfolio` | — | Gets the CAS (URL, local path, or upload link), parses it, enriches it, and summarises value, returns and top and bottom performers. |
| `portfolio_health_check` | `snapshot_id` (optional) | Composition, returns, concentration and overlap, ending with the 2–3 findings with the largest effect. |
| `compare_to_benchmarks` | `snapshot_id` (optional) | A 1Y and 3Y fund-versus-benchmark table, grouped into funds ahead on both horizons, behind on both, and mixed. |
| `tax_planning_india` | `snapshot_id`, `financial_year` (both optional) | Indicative realised and unrealised STCG and LTCG by tax class, from transactions. Needs a **detailed** CAS. Not tax advice. |

Leave `snapshot_id` blank to have the prompt parse a new CAS first.

The prompts ask the model to state findings with numbers and not to tell the user to buy, sell, hold or switch a named scheme. Portfolio Intel is not a SEBI-registered investment adviser.

## Getting the CAS to the agent

If the user doesn't have the PDF at hand, see [Get your CAS](https://docs.portfoliointel.co.in/guides/get-your-cas). It explains how to request one and how an agent that already has the user's own Gmail access can find the statement email and pass the attachment to `parse_cas`.

## Skills

Skills are higher-order analysis workflows that chain tools and apply domain-specific evaluation criteria. Unlike raw tools, skills produce structured reports with severity ratings and plain-English reasoning. See the [Skills](https://docs.portfoliointel.co.in/skills) page for details, available skills, and usage examples.

## Example workflow

```text
User asks an agent to parse a CAS and summarize the portfolio.

1. parse_cas → get snapshot_id and holdings
2. enrich → attach market context
3. agent summarizes current value, diversification, and available next actions
```

## Node.js example

```js
const fs = require('fs');

async function parseCAS(filePath, password) {
  const pdfBase64 = fs.readFileSync(filePath).toString('base64');

  const res = await fetch('https://api.portfoliointel.co.in/api/v1/parse', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_YOUR_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ pdf_base64: pdfBase64, password }),
  });

  const body = await res.json();
  if (!body.success) throw new Error(body.error.message);
  return body.data;
}
```

## Python example

```python
import base64
import requests

def parse_cas(file_path: str, password: str | None = None) -> dict:
    with open(file_path, 'rb') as handle:
        pdf_base64 = base64.b64encode(handle.read()).decode()

    resp = requests.post(
        'https://api.portfoliointel.co.in/api/v1/parse',
        headers={'Authorization': 'Bearer sk_live_YOUR_KEY'},
        json={'pdf_base64': pdf_base64, 'password': password},
    )
    resp.raise_for_status()
    return resp.json()['data']
```

## cURL sandbox example

```bash
# Sandbox samples are served by the web host, not api. — see Parse CAS → Sandbox samples
curl -X POST https://portfoliointel.co.in/api/v1/parse \
  -H "X-API-Key: sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pdf_ref":"sample_cams_2024"}'
```

Source: https://docs.portfoliointel.co.in/mcp/tools/
