Skip to content

Quickstart

By the end of this page you will:

  1. Have OpenMaskit running locally.
  2. Be connected to an upstream MCP server (a real one, not a mock).
  3. See a real value get masked on the way out and unmasked on the way back.

Total time: about five minutes.

1. Install and run

OpenMaskit is a Python CLI. The recommended installer is uv because uvx will fetch a compatible Python for you if you don't have one.

# one-line install of uv itself
curl -LsSf https://astral.sh/uv/install.sh | sh

# run OpenMaskit
uvx openmaskit

pipx install openmaskit
openmaskit

pipx does not auto-fetch Pythons, so you need Python 3.10+ installed already.

docker run --rm -p 9473:9473 -p 9474:9474 \
  -v $HOME/.openmaskit:/root/.openmaskit \
  ghcr.io/maskitmcp/openmaskit:latest

You should see startup logs ending with something like:

Dashboard:   http://127.0.0.1:9473
MCP HTTP:    http://127.0.0.1:9474

Open the dashboard at http://127.0.0.1:9473.

Storage location

OpenMaskit creates ~/.openmaskit/ on first run. That directory holds the masking config DB (store.db), the audit log DB (traffic.db), an encryption key (.key), and OAuth token files. Everything is local.

2. Add a server

Pick one of three ways to get an upstream MCP server connected:

A. From the marketplace (easiest)

Click Marketplace in the dashboard. Browse, click Install on something you have credentials for (Datadog, Supabase, GitHub, Postgres, etc.), fill in the env vars or credentials the install modal asks for, and Install.

B. A local stdio server

Open Servers → Add Server. Pick stdio, and enter a command. Example using the official MCP time server:

Name:    time
Command: uvx
Args:    mcp-server-time

C. A custom HTTP server

Open Servers → Add Server → HTTP. Enter the upstream URL and any required auth headers or OAuth config.

Whichever route you took, the server will appear in Active Servers within a second or two. Click into it to see the tools it advertises.

3. Connect your AI agent

Each connected server gets a stable HTTP MCP URL:

http://127.0.0.1:9474/{server_name}/mcp

For Claude Code, add the server via:

claude mcp add --transport http openmaskit-time http://127.0.0.1:9474/time/mcp

For Cursor, Codex CLI, and other MCP-capable hosts, follow your host's "Add HTTP MCP server" instructions and paste the same URL.

The dashboard's Connect agent button on each server card generates host-specific snippets.

4. See masking in action

Open a tool detail page (Servers → {your server} → {tool name}). You'll see four panes:

  • Schema — the tool's input/output schema as advertised upstream.
  • Try it out — call the tool from the dashboard with arbitrary arguments.
  • Masking rules — declare which fields in the response should be masked or stripped.
  • Output mappers — regex or JSON-path mappers that transform the output before masking.

Add a masking rule. For example, on time/get_current_time:

Tool name:  get_current_time
Field path: timezone
Action:     mask

Now invoke the tool via Try it out. In the masked response you'll see something like "timezone": "tz_1" instead of "America/New_York". The dashboard also shows what the agent sees vs. what the upstream returned.

When your agent later passes tz_1 back in another tool call, OpenMaskit transparently unmasks it to America/New_York before forwarding upstream.

That's the whole loop.

5. Where to go next

  • Concepts — what aliases, rules, mappers, guardrails, and injections actually mean.
  • Configuration — openmaskit.yaml reference and the env vars OpenMaskit reads.
  • Security model — what's local, what's not, and what attacks OpenMaskit defends against.