# MCP

Viraloop ships a Model Context Protocol (MCP) server so agent runtimes (Claude Code, Claude Desktop and any other MCP client) can call the API as tools. There are two ways to connect: the remote server over streamable HTTP, or a local stdio server bundled in the CLI. Both need an API key from https://viraloop.io/settings/developers.

## Remote server (nothing to install)

The remote server lives at `https://viraloop.io/api/v1/mcp` and speaks the streamable HTTP transport. Authenticate with the same `Authorization` header as the REST API:

```bash
claude mcp add --transport http viraloop https://viraloop.io/api/v1/mcp \
  --header "Authorization: Bearer vl_live_..."
```

Any MCP client that supports streamable HTTP works the same way: point it at the URL and send `Authorization: Bearer vl_live_...` with every request.

## Local server (stdio via the CLI)

The `viraloop` npm package includes a stdio MCP server, started with `viraloop mcp`. It reads the key from the `VIRALOOP_API_KEY` environment variable:

```bash
claude mcp add viraloop --env VIRALOOP_API_KEY=vl_live_... -- npx -y viraloop mcp
```

Use the remote server when you want zero install and always-current tools; use the local one when your client only speaks stdio or your network policy prefers a locally spawned process.

## Tools

Each tool wraps one API operation and respects the key's scopes (a missing scope surfaces as a `forbidden_scope` error):

- `viraloop_get_me`: introspect the API key (GET /me)
- `viraloop_get_credits`: credit balance and ledger (GET /credits)
- `viraloop_list_workspaces`: list workspaces (GET /workspaces)
- `viraloop_list_accounts`: list connected social accounts (GET /accounts)
- `viraloop_generate_content`: generate AI post suggestions (POST /generations)
- `viraloop_list_generations`: list suggestions (GET /generations)
- `viraloop_get_generation`: get a suggestion (GET /generations/{id})
- `viraloop_create_post`: create and schedule a post (POST /posts)
- `viraloop_list_posts`: list posts (GET /posts)
- `viraloop_get_post`: get a post with per-platform results (GET /posts/{id})
- `viraloop_cancel_post`: cancel a scheduled post (DELETE /posts/{id})

Tool results use the same envelope and error types as the REST API; see [errors and rate limits](/developers/docs/errors-and-rate-limits). Rate limits also apply per key, so a busy agent should back off on `rate_limited`.

## Related

- Prefer commands over tools? The [CLI](/developers/docs/cli) covers the same surface.
- A packaged Claude Skill with ready-made workflows lives at https://github.com/Viraloop/viraloop-skill.
- The full machine-readable surface is at https://viraloop.io/llms-full.txt and https://viraloop.io/openapi/v1.json.