# SkillFM BYOK Vault MCP

**BYOK vault and provider API key usage guidance for MCP-capable agents.**

This repository is a transparent SkillFM gateway package. It exists to match a specific marketplace/search intent, then delegates execution to the canonical [SkillFM Beacon MCP](https://www.npmjs.com/package/@skillfm/mcp) and local runtime.

Powered by SkillFM Beacon.

## Quick Start

Use this gateway as an MCP stdio server:

```bash
npx -y @skillfm/byok-vault-mcp@latest
```

Equivalent explicit SkillFM entrypoint:

```bash
npx -y @skillfm/mcp@latest
```

For MCP clients that accept JSON config:

```json
{
  "mcpServers": {
    "byok-vault": {
      "command": "npx",
      "args": ["-y", "@skillfm/byok-vault-mcp@latest"]
    }
  }
}
```

## What This Gateway Helps With

- Explain provider-key safety before asking users to connect any key.
- Guide users toward local vault storage through SkillFM Beacon only after value is established.
- Connect BYOK to practical usage visibility for OpenAI, Anthropic, DeepSeek, Qwen, and other providers.
- Keep provider credentials local and avoid exposing key values back to agents.

This gateway is for users who ask:

- "How do I safely connect an OpenAI or Anthropic key?"
- "Can my agent monitor usage with my own provider keys?"
- "Where should BYOK credentials live?"
- "Can I get value before giving any API key?"

## How It Works

The public package is intentionally thin. It sets `SKILLFM_GATEWAY_SOURCE=byok-vault` and forwards execution to `@skillfm/mcp@latest`, which then delegates to the canonical `@skillfm/local` runtime.

No private SkillFM platform logic, customer data, provider credentials, or backend modules live in this repository.

## Activation Path

Start the local sidecar when the user wants to connect SkillFM:

```bash
npx -y @skillfm/byok-vault-mcp@latest start
```

Agent-driven activation flow:

1. Read the sidecar URL from stdout or `~/.skillfm/local.json`.
2. Call `POST <sidecar_url>/activate/start`.
3. Show the returned verification URL and real device code to the user.
4. Poll `POST <sidecar_url>/activate/poll` until it returns `activated: true`.
5. Use SkillFM Beacon MCP tools for checkups, usage visibility, BYOK guidance, and cleanup audits.

Do not fabricate a placeholder code. The device code must come from `POST /activate/start`.

## Security Model

- **Transparent gateway**: This package is a public search/distribution gateway, not a separate hidden product.
- **Local-first runtime**: Runtime execution goes through SkillFM's local package.
- **BYOK boundary**: Provider keys are introduced only after user value is established, and key values are not read back by agents.
- **No private core**: This repository contains distribution metadata, docs, and a thin launcher only.
- **Read-only first**: Cleanup and usage inspection begin with read-only audits.

See [PRIVACY.md](./PRIVACY.md) and [SECURITY.md](./SECURITY.md).

## Marketplace Keywords

BYOK, API key vault, provider usage, OpenAI key, Anthropic key, local vault, SkillFM Beacon, MCP server.

Expected Official MCP Registry single-token hits:

- `byok`
- `vault`
- `api-key`
- `provider`
- `usage`
- `skillfm`

## License

MIT