🔌 MCP Server Integration

Install

npm install soulprint-mcp

Basic Usage

Wrap any MCP tool handler with requireSoulprint():

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { requireSoulprint } from "soulprint-mcp";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

// 🔓 Public tool — no identity required
server.tool("public-info", {}, async () => ({
  content: [{ type: "text", text: "Open to everyone" }]
}));

// 🔐 Protected tool — requires score ≥ 60
server.tool(
  "premium-search",
  { query: z.string() },
  requireSoulprint({ minScore: 60 }),
  async (args, ctx) => {
    const { did, score } = ctx.soulprint;
    // 'did' = "did:soulprint:abc123..."
    // 'score' = 72  (identity + reputation combined)
    return {
      content: [{ type: "text", text: `Results for: ${args.query}` }]
    };
  }
);

Configuration Options

Score Tiers — Recommended Thresholds

Accessing Identity Context

When the middleware passes, ctx.soulprint contains:

interface SoulprintContext {
  did:         string;       // "did:soulprint:abc123..."
  score:       number;       // 0–100 combined trust score
  identity:    number;       // 0–80 identity sub-score
  reputation:  number;       // 0–20 bot reputation sub-score
  country:     string;       // "CO", "MX", "BR"…
  credentials: string[];    // ["email","document","face_match",…]
  expiresAt:   string;       // ISO timestamp
  verified:    boolean;      // token signature valid
}

Token Lookup — Header Priority

The middleware reads the token from these headers (in order):

1. x-soulprint-token — MCP-native capability header
2. X-Soulprint — standard HTTP header
3. Authorization: Bearer <token> — OAuth-compatible

Error Handling

When access is denied, the middleware returns a structured MCP error:

{
  "error": {
    "code": -32003,
    "message": "Soulprint: insufficient trust score. Required: 60, got: 42",
    "data": {
      "required": 60,
      "actual": 42,
      "did": "did:soulprint:abc123..."
    }
  }
}

Express / Fastify Middleware

For REST APIs (non-MCP), use soulprint-express:

npm install soulprint-express

import express from "express";
import { soulprintMiddleware } from "soulprint-express";

const app = express();

// Apply globally — all routes below require score ≥ 40
app.use(soulprintMiddleware({ minScore: 40 }));

// Or apply per-route
app.post(
  "/apply-job",
  soulprintMiddleware({ minScore: 40 }),
  (req, res) => {
    const { did, score, country } = req.soulprint;
    res.json({ accepted: true, applicant: did });
  }
);

Full Example — mcp-colombia-hub

The mcp-colombia-hub package is the reference implementation of Soulprint in a production MCP server. It uses withTracking() to wrap every tool call and automatically issues behavioral attestations:

import { withTracking } from "soulprint-mcp";

// Wraps the tool + tracks usage for reputation scoring
server.tool(
  "ml_buscar_productos",
  { query: z.string(), limit: z.number().optional() },
  withTracking({ minScore: 0, toolName: "ml_buscar_productos" }),
  handler
);