# `vpa360-import` skill — install guide

Self-contained Claude skill that teaches Claude Web / Claude Excel /
Claude Code how to drive the VPA360 Import Tool's MCP server.

You are reading this from **https://dev.data-extractor.vpa-360.com** — substitute that host into the
snippets below. Sharing this URL with another user gets them everything
they need to install.

## What's here

| File | Purpose |
|---|---|
| [`SKILL.md`](https://dev.data-extractor.vpa-360.com/skill/SKILL.md) | The skill itself. Frontmatter (`name`, `description`) plus instructions for the LLM on when/how to use the MCP tools. Connection-agnostic. |
| [`README.md`](https://dev.data-extractor.vpa-360.com/skill/README.md) | This file — install instructions for *this specific* deployment. |

## Endpoints for this deployment

```
Web UI:        https://dev.data-extractor.vpa-360.com/
MCP:           https://dev.data-extractor.vpa-360.com/mcp        (Streamable HTTP, single endpoint)
```

Auth on every MCP request:

```
Authorization: Bearer <your-token>
```

## Install

### Claude Code (per-user)

```sh
mkdir -p ~/.claude/skills/vpa360-import
curl -k -o ~/.claude/skills/vpa360-import/SKILL.md \
  https://dev.data-extractor.vpa-360.com/skill/SKILL.md
```

Then add the MCP server to your Claude Code MCP config (e.g.
`~/.claude.json` or `claude mcp add`):

```json
{
  "mcpServers": {
    "vpa360-import": {
      "type": "http",
      "url": "https://dev.data-extractor.vpa-360.com/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}
```

### Claude Code (project-scoped)

Drop the file at `.claude/skills/vpa360-import/SKILL.md` inside any project
where you want it active. Add the same MCP server entry to that project's
`.mcp.json`.

### Claude Desktop

1. Add the MCP server in **Settings → Connectors → Add custom integration**.
   - Name: `VPA360 Import`
   - Type: `MCP server (Streamable HTTP)`
   - URL: `https://dev.data-extractor.vpa-360.com/mcp`
   - Header: `Authorization: Bearer <your-token>`
2. Share `SKILL.md` with the assistant by uploading it as a project file or
   pasting its contents into the project's instructions panel.

### Claude Web (claude.ai)

Claude Web does not accept a raw bearer token; it speaks OAuth 2.1.

1. **Connector.** In **Settings → Connectors → Add custom integration**,
   point at `https://dev.data-extractor.vpa-360.com/mcp`. Claude.ai discovers the authorization
   server automatically via `/.well-known/oauth-protected-resource/mcp`
   and self-registers as a public client through `/register` (RFC 7591).
2. **Sign in.** On first use you will be redirected to
   `https://dev.data-extractor.vpa-360.com/oauth/authorize` and prompted for a username and
   password. Credentials are issued out-of-band by the deployment
   operator (entries live in `config/users.yaml` on the server). If
   you don't have one, ask whoever stood up this deployment.
3. **Allow network egress to this host.** Workbook uploads run on
   Claude's code-execution sandbox, which is firewalled by default —
   you must allowlist the deployment host or the agent's `curl` /
   `requests.post` call will fail with "Could not resolve host" /
   "Connection refused".

   *Personal plans (Free / Pro / Max).* **Settings → Capabilities** →
   toggle **Code execution and file creation** on → toggle **Allow
   network egress** on → pick **"Allow network egress to package
   managers and specific domains"** → add the host portion of
   `https://dev.data-extractor.vpa-360.com` to the list.

   *Team plan.* The toggle lives at **Organization settings →
   Capabilities** and is admin-only. By default Team is restricted to
   package managers; ask your workspace admin to add the host.

4. **Token lifetime.** Claude.ai stores the issued JWT and uses it as
   the Bearer token on every MCP call. Tokens expire after 24h;
   revisit the connector to re-authorize.

### Claude for Excel

The Excel add-in talks to the same MCP server. Connect it via the same URL
+ Bearer header in the add-in's settings. The skill file is loaded the same
way as for Claude Web.

## Notes

- The `SKILL.md` file is host-agnostic and won't change between
  deployments. Only this README rewrites itself with the deployment URL.

## Updating

Re-fetch the files from `https://dev.data-extractor.vpa-360.com/skill/` when the tool surface changes.
The MCP server's `list_tools` response is also self-describing — agents
that don't load the skill file will still get enough metadata to drive the
three tools correctly.