# Connecting an agent

PIG is a first-class application for agents. The same MCP server serves every
client, so nobody is asked to use a different tool than the one they already
work in.

This page is about connecting *your* agent to PIG. **Piggy**, the agent that
lives inside PIG, is a different thing: it drains a database queue, and in chat
it runs a Prime Agent session over PIG's own tools for whoever is looking at the
page — reading and citing records, and proposing changes the user approves. It
is described in the README under *The agent surface*, and the engineering
account, including the traps, is AGENTS.md §6.

## Transport, and what that means for you

The MCP server speaks **stdio only**. There is no Streamable HTTP transport and
no `/mcp` endpoint on the API, so each person runs their own copy locally
against their own API key rather than pointing a client at a shared URL. That is
a real limitation, not a security posture — see the build plan.

`@pig/mcp` is a workspace package and is **not published to npm**, so `npx
@pig/mcp` does not work. Run it out of a clone.

## Setup

Create an API key in PIG under **Settings → API keys** — the plaintext is shown
once — then:

```bash
export PIG_URL=https://primeintellectgrowth.com
export PIG_API_KEY=pig_...
```

Scope the key to `read` unless the agent genuinely needs to write. An agent
acting for you is a **separate principal** from you: it has its own audit trail
and can be revoked without disturbing your session, and it can never reach
further than you can — on a write, the key's `write` scope is checked first and
then your own capability for that team.

⚠️ **Reads are not yet gated.** The read policy exists and is tested but is not
mounted in `app.ts`, so a `read`-scoped key currently reaches every GET in the
product, including supplier cost and margin. Treat any key you mint as
cost-visible until that lands.

## What connects

| Client | How |
|---|---|
| **Claude Code** | `claude mcp add pig -- pnpm --dir /path/to/pig exec tsx apps/mcp/src/stdio.ts` |
| **Codex** | Add the same command as an MCP server in its config, with the same two environment variables |
| **prime-agent** | It is an MCP *client*; register the same stdio command |
| **Buzz** | Agents reach PIG through the ACP bridge's MCP support |

## CLI

The `pig` CLI is the HTTP API surface for scripts and Prime Agent kernels. It
never receives database credentials and has no arbitrary-request, shell, or
filesystem command. Configure it separately from the MCP process:

```bash
export PIG_API_URL=https://primeintellectgrowth.com
export PIG_API_KEY=pig_...

pnpm run pig -- me
pnpm run pig -- --json capacity idle --threshold 0.2
pnpm run pig -- --json capacity search --gpu-type H100_80GB --min-gpu-count 8
```

`--api-url` and `--api-key` override the environment for one invocation. In
`--json` mode success writes one JSON value to stdout, while failures write one
JSON error to stderr and exit non-zero. The key is sent only as a bearer token
and is redacted if an upstream error happens to echo it.

## The tools

| Tool | What it answers |
|---|---|
| `pig_whoami` | Who am I acting for, and which teams am I on? |
| `pig_my_pipeline` | Where are we? What needs attention? |
| `pig_capacity_match` | What have we bought that would serve this customer? |
| `pig_margin_report` | What is each block earning against what it cost? |
| `pig_idle_capacity` | What are we paying for and not selling? |
| `pig_inventory_search` | What could we buy to cover demand we cannot serve? |
| `pig_search` | Find an account |
| `pig_get_account` | Everything about one account |
| `pig_motion_library` | What practice have we already written for this stage? |
| `pig_log_activity` | Record a call, meeting or note |

`pig_capacity_match` is the one worth learning. Ask it in plain language:

> "A customer wants 128 H100s with InfiniBand for three months, ceiling $2.80
> per GPU-hour. What have we got?"

It returns ranked matches, preferring blocks that are sitting idle — those
hours are already paid for — and warns explicitly when a match would sell below
break-even.

## Why the surface is small

Ten tools, each doing one thing. A sprawling tool list measurably degrades
model performance, and anything genuinely niche is reachable through
`pig_search` or the HTTP API. If you need something that is not here, it is
probably better added as a service method than as an eleventh tool.

## What it cannot do

The MCP server holds an API key and calls the same HTTP API a browser does. It
has no database credentials and no privileged path. There is deliberately no
tool that provisions infrastructure, spends money, or emails a customer.