# Pine API and MCP server

Pine runs locally inside Pi. This public service answers questions about Pine itself: the latest release and its checksums, the installation steps, and where the documentation covers a topic. It is read-only, needs no account or key, and never installs anything or reads your project.

Use it when an agent is installing Pine, verifying a download, or looking up how a Pine feature works. For the work itself, use Pine's local tools inside Pi (`pine_view`, `pine_records`, `pine_agent`, `pine_manage` and `pine_recall`).

## REST API

Base address: `https://pine-pi.vercel.app/api/v1`. Every response is JSON. The [OpenAPI description](https://pine-pi.vercel.app/openapi.json) lists the schemas, and the [API catalog](https://pine-pi.vercel.app/.well-known/api-catalog) links it for discovery.

| Operation | Request | Returns |
| --- | --- | --- |
| `getRelease` | `GET /api/v1/release` | Version, release page, the `pi install` command and the SHA-256 checksum of each renderer binary |
| `getInstallSteps` | `GET /api/v1/install` or `GET /api/v1/install?step=4` | Numbered steps from the [installation guide](https://pine-pi.vercel.app/install.md) with exact commands and where to run them |
| `searchDocs` | `GET /api/v1/docs/search?q=custom+agents&limit=5` | Matching documentation sections with links and short excerpts |

Try it:

```sh
curl -s https://pine-pi.vercel.app/api/v1/release
curl -s "https://pine-pi.vercel.app/api/v1/docs/search?q=feedback"
```

## MCP server

Connect any Streamable HTTP MCP client to `https://pine-pi.vercel.app/mcp`. The server is stateless and offers three read-only tools that match the REST operations:

- `pine_get_release`: the latest release, install command and checksums.
- `pine_get_install_steps`: every installation step, or one step with `{"step": 4}`.
- `pine_search_docs`: documentation sections for `{"query": "widgets", "limit": 5}`.

Discovery files: the [MCP server card](https://pine-pi.vercel.app/.well-known/mcp/server-card.json), the [AI catalog](https://pine-pi.vercel.app/.well-known/ai-catalog.json) and [registry metadata](https://pine-pi.vercel.app/server.json).

## Errors

Errors use RFC 9457 problem details (`application/problem+json`) with a stable `code`, a `detail` and a `hint` that says how to fix the request.

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `missing_query`, `query_too_long`, `invalid_limit`, `invalid_step` | A parameter is missing or out of range |
| 404 | `not_found`, `step_not_found` | No such endpoint or installation step |
| 405 | `method_not_allowed` | The API is read-only; use `GET` |
| 500 | `internal_error` | Retry once, then report the problem on GitHub |

MCP errors follow JSON-RPC: an unknown method returns `-32601`, an unknown tool `-32602`, and invalid tool arguments return a tool result with `isError: true` and the reason.

## Versions and deprecation

Stable operations live under `/api/v1`. Changes within v1 only add fields or operations. A breaking change gets a new major path such as `/api/v2`, and v1 keeps working for at least 90 days afterwards. During that time v1 responses carry `Deprecation` and `Sunset` headers (RFC 9745 and RFC 8594) with a `Link` to the replacement, and this page lists the dates. No version is deprecated today.

## Limits and privacy

Answers describe the published release and this site's documentation. Search queries are processed to answer the request and are not stored by Pine. Do not send credentials or private project content. Report problems at [GitHub issues](https://github.com/johnlindquist/pine/issues).