Quick Start

Install the MCP Client, verify your system, and run your first certified MCP package in minutes.

  5 min read  

This guide walks you through installing the MCP Client, checking your system capabilities, authenticating with a registry, and running your first MCP package.

Prerequisites

RequirementMinimum VersionCheck Command
Go1.24+go version
MakeAnymake --version
Git2.30+git --version

Step 1: Install the MCP Client

Build from Source

Clone the repository and build the binary:

git clone https://github.com/your-org/mcp-hub-platform.git
cd mcp-hub-platform/mcp-client
make build

This produces the mcp binary in the current directory. Optionally, install it system-wide:

make install

This copies the binary to $GOPATH/bin/mcp.

Verify the Installation

mcp --version

You should see output similar to:

mcp version 1.0.0 (commit: abc1234, built: 2025-01-15T10:00:00Z)

Step 2: Check System Capabilities

Run the built-in diagnostic tool to understand what sandboxing features are available on your system:

mcp doctor

Example Output (Linux)

MCP Client System Diagnostics
==============================

Platform:           linux (amd64)
Go Version:         1.24.1

Sandbox Capabilities:
  Resource Limits:  OK (cgroups v2 + rlimits)
  Network Isolation: OK (network namespaces)
  Filesystem:       OK (bind mounts + Landlock)
  Subprocess Ctrl:  OK (seccomp)

Registry Connectivity:
  Default Registry:  OK (https://registry.mcp-hub.io)
  Latency:          45ms

Cache:
  Directory:        ~/.mcp/cache
  Size:             0 B (empty)

Overall:            PRODUCTION READY

Example Output (macOS)

MCP Client System Diagnostics
==============================

Platform:           darwin (arm64)
Go Version:         1.24.1

Sandbox Capabilities:
  Resource Limits:  PARTIAL (rlimits only, no cgroups)
  Network Isolation: NOT AVAILABLE
  Filesystem:       PARTIAL (best-effort UNIX permissions)
  Subprocess Ctrl:  LIMITED

Registry Connectivity:
  Default Registry:  OK (https://registry.mcp-hub.io)
  Latency:          62ms

Cache:
  Directory:        ~/.mcp/cache
  Size:             0 B (empty)

Overall:            DEVELOPMENT ONLY -- not recommended for untrusted MCPs

Step 3: Log In to the Registry

Authenticate with the MCP Hub registry to access packages:

mcp login

This opens an interactive login flow. You will be prompted for your registry URL and credentials:

Registry URL [https://registry.mcp-hub.io]:
Username: [email protected]
Password: ********

Login successful. Token stored in ~/.mcp/auth.json

For non-interactive environments (CI/CD pipelines), use a token directly:

mcp login --registry https://registry.mcp-hub.io --token $MCP_REGISTRY_TOKEN

To verify your authentication status:

mcp info --auth-status

Step 4: Pull Your First Package

Download a package without executing it:

mcp pull acme/[email protected]

Expected output:

Resolving acme/[email protected]...
  Manifest:  sha256:a1b2c3d4e5f6...
  Bundle:    sha256:f6e5d4c3b2a1...
  Cert Level: 2 (Security Certified)
  Origin:    Verified

Downloading bundle... 2.3 MB
Validating SHA-256 digest... OK

Package cached at ~/.mcp/cache/sha256/a1b2c3d4e5f6...

The client performs the following steps automatically:

  1. Resolves the package reference to a specific manifest and bundle digest
  2. Downloads the bundle from the registry (or uses presigned URLs from S3)
  3. Validates the SHA-256 digest to ensure integrity
  4. Caches the artifact locally so subsequent runs are instant

Step 5: Run the Package

Execute the downloaded MCP server:

mcp run acme/[email protected]

Output:

Resolving acme/[email protected]... (cached)
Validating digest... OK
Applying security policy... OK
  Cert Level: 2 >= required 0 ✓
  Origin: Verified ∈ [Official, Verified, Community] ✓

Starting MCP server (STDIO transport)...
  PID:     12345
  Memory:  256 MB limit
  CPU:     1.0 cores
  PIDs:    64 max
  Network: deny-all

Server ready. Listening on STDIO.

The client:

  1. Checks the local cache (skips download if already cached)
  2. Re-validates the SHA-256 digest
  3. Enforces your configured security policies
  4. Launches the MCP server inside a sandbox with resource limits
  5. Connects via STDIO transport

Press Ctrl+C to stop the server gracefully.

Step 6: Inspect Package Details

View detailed information about any package:

mcp info acme/[email protected]

Package:       acme/[email protected]
Manifest:      sha256:a1b2c3d4e5f6...
Bundle:        sha256:f6e5d4c3b2a1...
Cert Level:    2 (Security Certified)
Score:         85/100
Origin:        Verified
Language:       Python 3.11
Transport:     STDIO
Published:     2025-01-10T14:30:00Z

Tools:
  - greet          Greet a user by name
  - farewell       Say goodbye to a user

Resources:
  - templates/     Greeting templates directory

Findings:      0 critical, 0 high, 2 medium, 5 low

Understanding the Output

Certification Levels

Every package displays its certification level, which indicates the depth of security analysis it has passed:

LevelNameWhat It Means
0Integrity VerifiedDigest and schema validated only
1Static VerifiedBasic static analysis, score >= 60
2Security CertifiedFull security analysis, score >= 80
3Runtime CertifiedDynamic analysis included, score >= 90

Origin Types

The origin indicates who published the package and their verification status:

OriginMeaning
OfficialMaintained by the MCP Hub team
VerifiedPublisher identity has been verified
CommunityPublished by any user, no identity guarantees

Common Quick Start Issues

“registry not reachable”

If mcp doctor reports the registry as unreachable, verify the URL:

mcp doctor --registry https://registry.mcp-hub.io

For local development, point to your local registry:

mcp doctor --registry http://localhost:8081

“authentication required”

Some packages require authentication. Make sure you have logged in:

mcp login

“sandbox capabilities limited”

On macOS or Windows, the client will warn about limited sandboxing. This is expected. For development and testing, this is acceptable. For production use with untrusted MCPs, use Linux.

Next Steps