# Toolcapsule

> Use when: turning MCP servers into lazy Agent Skills, calling MCP tools with inline JSON or local files, or looking up MCP tool schemas on demand.

- Skill: `rainsunme/toolcapsule` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rainsunme/toolcapsule`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rainsunme/toolcapsule/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: RainSunMe (https://skillmd.com/u/rainsunme)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rainsunme/toolcapsule

---


# ToolCapsule

ToolCapsule converts heavy MCP tools into compact, lazy-loaded Agent Skills. MCP stays the capability layer; Skills become the agent-facing workflow layer.

## Getting started (Agent reads this first)

1. Check if the `tcap` CLI is available. If not, install it:

```bash
npm install -g toolcapsule
tcap --version
```

2. Now you can use the commands below to register MCP servers and call their tools.

## Core workflow

### 1. Register an MCP server and generate a Skill

```bash
# Remote MCP
tcap init <profile-name> --url <mcp-url> --target claude

# Local stdio MCP
tcap init <profile-name> --command <cmd> --arg <arg> --target claude
```

This creates:
- `~/.toolcapsule/profiles/<profile-name>.json` (transport config — never commit)
- Skills directory with `SKILL.md` (safe to commit)

Supported targets: `agents` (default), `copilot`, `claude`, `opencode`, `all`.

### 2. Read the generated SKILL.md

The Skill contains a compact tool summary. Always prefer it over loading full MCP schemas.

### 3. Look up detailed schema on demand

```bash
tcap tools <profile>                 # compact one-line summary
tcap tools <profile> --names         # tool names only
tcap tools <profile> --json          # raw JSON
tcap schema <profile> <tool>         # compact schema for one tool
```

### 4. Call tools with inline JSON or /tmp files

```bash
# Use inline JSON for simple args
tcap call <profile> <tool> '{"key":"value"}'

# Use /tmp files for larger or frequently patched args (never the workspace)
tcap call <profile> <tool> @/tmp/tcap-<profile>-<tool>.json

# Save response to a file (avoids large responses flooding context)
tcap call <profile> <tool> @/tmp/tcap-<profile>-<tool>.json -o /tmp/tcap-<profile>-response.json
```

If a file-based call fails, edit the args file and re-run the same command. For simple one-off calls, inline JSON is fine.

## Profile management

Profiles are stored in `~/.toolcapsule/profiles/` only. They contain transport config (URLs, commands, credentials) and must never be committed to a repository.

List profiles:

```bash
ls ~/.toolcapsule/profiles/
```

## Safety

- Never print or commit MCP URLs, tokens, API keys, or credentials.
- For large, sensitive, or retryable payloads, write call args to `/tmp`, never to the workspace.
- Profile JSON files in `~/.toolcapsule/profiles/` are private — do not read their contents to the user.
- Set `TOOLCAPSULE_DEBUG=1` only for debugging stderr output.