MCP Gateway Quickstart

Prerequisites

This quickstart is for the experimental MCP Gateway release candidate. Use @admissible-ai/mcp-gateway@experimental.

• Node.js 18 or later and npm
• An MCP client that supports stdio server configuration
• Admissible API URL
• ADMISSIBLE_API_KEY
• Filesystem MCP server access through npx or a local binary

Need an API key? Create a Sandbox account.

Quickstart

Start with the filesystem server. It gives a deterministic local proof before any external service or token enters the loop.

1. Confirm release candidate status

   Status: @admissible-ai/mcp-gateway is published as an experimental release candidate. Use the @experimental dist tag in public install guidance.

   Command

   # MCP Gateway is an experimental release candidate.# Use the experimental dist tag until the package is promoted.

2. Install and initialize

   Use the @experimental dist tag while MCP Gateway remains an experimental release candidate.

   Command

   npm install -g @admissible-ai/mcp-gateway@experimentaladmissible-mcp init --config admissible.mcp.yaml

3. Internal RC / local package smoke

   Skip this unless you are reviewing the package candidate from an internal checkout or approved tarball.

   Command

   # Internal RC / local package smoke only.# Use an approved local workspace package or packed RC tarball.admissible-mcp init --config admissible.mcp.yaml

4. Create a filesystem sandbox

   Filesystem is the stable local example. GitHub is a disposable-repo pilot only.

   Command

   mkdir -p mcp-sandbox/allowed-output mcp-sandbox/secretsprintf "Filesystem MCP sandbox.\n" > mcp-sandbox/README.mdprintf "do-not-read\n" > mcp-sandbox/.envprintf "hidden\n" > mcp-sandbox/secrets/hidden.txt

5. Configure the filesystem MCP server

   Every discovered MCP tool resolves to a Tool Contract before execution.

   admissible.mcp.yaml

   admissible:  baseUrl: ${ADMISSIBLE_API_URL}  apiKey: ${ADMISSIBLE_API_KEY}​gateway:  mode: local-proxy  transport: stdio  metadataMode: metadata-first  manifestPath: .admissible/mcp-manifest.json  auditLogPath: .admissible/mcp-audit.jsonl​servers:  filesystem:    command: npx    requestTimeoutMs: 30000    args:      - --yes      - --package      - "@modelcontextprotocol/server-filesystem"      - mcp-server-filesystem      - ./mcp-sandbox    contracts:      read_file:        kind: read_only        commitClass: none        scopes:          - ./mcp-sandbox/**        deny:          - ./mcp-sandbox/.env          - ./mcp-sandbox/secrets/**        approvalPolicy: never      write_file:        kind: local_write        commitClass: local        scopes:          - ./mcp-sandbox/allowed-output/**        approvalPolicy: on_yellow

6. Point your MCP client at the gateway

   The MCP client talks to the local gateway, and the gateway launches the configured MCP server.

   MCP client config

   {  "mcpServers": {    "admissible": {      "command": "admissible-mcp",      "args": ["serve", "--config", "./admissible.mcp.yaml"]    }  }}

7. Run an allowed read and a blocked write

   README.md is forwarded. .env is blocked locally. The state-changing write is deferred at commit admission before the filesystem server receives it.

   Command

   # In your MCP client:# 1. Call filesystem.read_file or filesystem.read_text_file for README.md.# 2. Call the same read tool for .env.# 3. Call filesystem.write_file for allowed-output/commit-deferred.txt.

8. Inspect the local audit log

   Look for contractKind, commitClass, executeTraceId, commitDecision, and serverExecuted.

   Command

   tail -n 20 .admissible/mcp-audit.jsonl

What this run does

This example configures the local gateway as the MCP client target, launches the official filesystem MCP server behind it, and routes tool calls through Admissible before execution.

• The MCP client connects to admissible-mcp serve instead of connecting directly to the filesystem server.
• The gateway resolves read and write tools into Tool Contracts before calling /v2/execute.
• Read-only calls can execute after allow; local denies and commit deferrals stop before the filesystem MCP server receives the call.

MCP client -> admissible-mcp serve  -> Tool Contract  -> /v2/execute  -> /v2/commit for state-changing tools  -> MCP server only after allow

What you should see

A successful first run should make the allowed path and the runtime decision easy to spot.

• README.md read reaches the filesystem MCP server
• .env read is blocked before the filesystem MCP server receives it
• allowed-output/commit-deferred.txt write is deferred at commit admission
• audit entries include Tool Contract and commit metadata
• serverExecuted is false for denied or deferred calls