Freedom World MCP Server: AI Agent Blockchain Tools

What Is the Freedom World MCP Server?

The Freedom World MCP server is an open-source TypeScript server implementing the Model Context Protocol that gives any MCP-compatible AI agent programmatic access to blockchain-backed reputation scoring, Suriya merchant commerce, and agent wallet infrastructure through a single configuration block.

The Freedom World MCP server is a TypeScript server that implements the Model Context Protocol specification. It gives any MCP-compatible AI client — Claude Desktop, Claude Code, ChatGPT, Cursor, Windsurf, or custom agents — programmatic access to two platform APIs:

Freedom World API (api.freedom.social) — community reputation management, point systems, and tier tracking

Suriya API (build.suriya.ai) — merchant onboarding, product catalogs, order management, Stripe payment processing, and revenue analytics

The server runs locally via Node.js and communicates over stdio transport. It authenticates with bearer tokens. No hosted infrastructure required on your side.

Why this matters for developers: If you are building AI agents that need to understand user trust levels, process model context protocol payments, manage merchant operations, or hold their own wallets — the Freedom World MCP server gives you access to all of that through a protocol your AI client already speaks. It is one of the first MCP server blockchain integrations that combines reputation with commerce.

Key Takeaway: The Freedom World MCP server is one of the only MCP integrations that combines blockchain reputation, live payment processing (Stripe + PromptPay), full merchant lifecycle management, and upcoming agent wallet identity — replacing four separate integrations with a single configuration block.

Available Tools Today

The Freedom World MCP server exposes 15 tools across four categories. Eleven are live and hitting production APIs. Four are Phase 2 placeholders.

Quickstart in 5 Minutes

Prerequisites

• Node.js 18+
• A Freedom World access token (get one at freedom.world)
• (Optional) A Suriya API key for merchant tools

Install and Build

git clone https://github.com/anthropics/freedom-mcp-server.git
cd freedom-mcp-server
npm install
npm run build

Set Environment Variables

export FREEDOM_ACCESS_TOKEN="your-token-here"
export FREEDOM_API_URL="https://api.freedom.social"    # default
export FREEDOM_COMMUNITY_ID="507"                       # default
export SURIYA_API_URL="https://build.suriya.ai"         # for merchant tools
export SURIYA_API_KEY="your-suriya-key"                 # for merchant tools

Claude Desktop Configuration

Add this block to your claude_desktop_config.json to connect the freedom world mcp server:

{
  "mcpServers": {
    "freedom-world": {
      "command": "node",
      "args": ["/path/to/freedom-mcp-server/dist/index.js"],
      "env": {
        "FREEDOM_API_URL": "https://api.freedom.social",
        "FREEDOM_COMMUNITY_ID": "507",
        "FREEDOM_ACCESS_TOKEN": "your-token",
        "SURIYA_API_URL": "https://build.suriya.ai",
        "SURIYA_API_KEY": "your-suriya-key"
      }
    }
  }
}

Replace /path/to/freedom-mcp-server with the absolute path to where you cloned the repository. Replace the token and key values with your actual credentials.

Verify It Works

Open Claude Desktop. In a new conversation, type:

"List the available point types in Freedom World."

Claude will call the list_point_types tool and return the seven point categories. If you see the response, the MCP server blockchain connection is live.

Reputation Tools

Freedom World's reputation tools expose a four-tier scoring system (Bronze through Platinum) across seven activity categories — letting AI agents query, award, and respond to trust scores programmatically as part of any workflow.

The reputation system is the foundation of Freedom World's community layer. Every user accumulates points across seven categories, which roll up into a tiered score.

How Tiers Work

Seven Point Types

Each point type maps to a specific kind of activity:

• custom_points — manually awarded for custom activities
• poster_points — earned by creating posts
• commenter_points — earned by commenting on posts
• chat_points — earned by participating in chat
• shop_points — earned through marketplace activity
• topup_points — earned through top-up/payment activity
• mission_points — earned by completing missions and tasks

get_user_reputation

Returns the full points breakdown and total score for a user in a community.

MCP tool call:

{
  "name": "get_user_reputation",
  "arguments": {
    "user_id": "12345",
    "community_id": "507"
  }
}

Example response:

{
  "payload": {
    "user_id": "12345",
    "community_id": "507",
    "custom_points": 150,
    "poster_points": 80,
    "commenter_points": 45,
    "chat_points": 30,
    "shop_points": 200,
    "topup_points": 50,
    "mission_points": 75,
    "total_score": 630
  }
}

This user has a total score of 630, placing them in the Gold tier.

award_points

Award points to one or more users in a single call. Requires a reason string for audit logging.

{
  "name": "award_points",
  "arguments": {
    "updates": [
      { "user_id": "12345", "points": 50, "point_type": "mission_points" },
      { "user_id": "67890", "points": 25, "point_type": "custom_points" }
    ],
    "reason": "Completed Q1 onboarding tasks"
  }
}

Real-world use cases for award_points:

• AI-moderated communities — a Bangkok co-working space runs a Freedom World community where an AI agent monitors the chat channel, identifies helpful answers from members, and awards commenter_points automatically
• Automated mission completion — a retail merchant uses the freedom world mcp server to verify customers completed an onboarding checklist, then awards mission_points without manual intervention
• Referral programs — award custom_points when an agent detects a successful referral event from the merchant's app

check_user_standing

Returns the user's score, tier, and the full tier threshold map.

{
  "name": "check_user_standing",
  "arguments": {
    "user_id": "12345"
  }
}

Example response:

{
  "user_id": "12345",
  "score": 630,
  "tier": "Gold",
  "thresholds": {
    "Bronze": "0-99",
    "Silver": "100-499",
    "Gold": "500-1999",
    "Platinum": "2000+"
  }
}

Use case: Gate features or content behind reputation tiers. Your agent checks standing before granting access to a premium channel, exclusive product, or elevated permissions.

Key Takeaway: Freedom World's reputation tools make trust queryable — your AI agent can check a user's tier before processing a high-value request, award mission points automatically, and gate premium features behind earned reputation. Reputation is data your agent reads and writes, not a static badge.

Commerce Tools

The Freedom World commerce tools connect AI agents to the full Suriya merchant lifecycle — from business setup and product catalog management through live payment processing (Stripe + PromptPay) and revenue analytics — all via standard MCP tool calls.

The commerce tools connect to the Suriya merchant platform. They give AI agents the ability to manage the full merchant lifecycle — from setup to analytics. These are among the most complete AI agent developer tools blockchain has to offer for Southeast Asian commerce.

create_payment_link

Creates a Stripe PaymentIntent with support for card and PromptPay (for THB transactions). Amount is in the smallest currency unit — satang for THB, so 12000 satang = 120 baht.

{
  "name": "create_payment_link",
  "arguments": {
    "merchant_id": "roast-bangkok",
    "amount": 12000,
    "description": "Order #abc123",
    "currency": "thb"
  }
}

Response:

{
  "ok": true,
  "merchant_id": "roast-bangkok",
  "amount": 12000,
  "currency": "thb",
  "client_secret": "pi_3abc...secret_xyz",
  "payment_intent_id": "pi_3abc...",
  "payment_methods": ["card", "promptpay"]
}

Use the client_secret with Stripe.js or Stripe Elements to render the checkout UI on the customer side. This is a live model context protocol payments integration — not a sandbox.

get_orders

Fetch orders for a merchant, sorted newest-first. Filter by status: pending, confirmed, completed, or cancelled.

{
  "name": "get_orders",
  "arguments": {
    "merchant_id": "roast-bangkok",
    "limit": 10,
    "status": "pending"
  }
}

Use case: An AI agent monitors pending orders and notifies the merchant via LINE or chat when a new order arrives. It flags orders pending for over 15 minutes so staff can prioritize.

get_merchant_analytics

Returns revenue metrics over a configurable period (7, 30, or 90 days). Includes GMV, order count, average order value, top products, daily revenue chart, and period-over-period comparison.

{
  "name": "get_merchant_analytics",
  "arguments": {
    "merchant_id": "roast-bangkok",
    "period": "30"
  }
}

Response structure:

{
  "merchant_id": "roast-bangkok",
  "period_days": 30,
  "gmv": 185000,
  "order_count": 142,
  "aov": 1302,
  "top_products": ["Flat White", "Cold Brew", "Croissant"],
  "daily_chart": [{"date": "2026-03-12", "revenue": 6200}],
  "vs_last_period": { "gmvChange": 12.5 }
}

Use case: An AI agent generates a weekly business report highlighting revenue trends, best-selling items, and 12.5% growth vs. the previous period — all from one tool call.

add_product

Add a product or menu item to the merchant catalog.

{
  "name": "add_product",
  "arguments": {
    "merchant_id": "roast-bangkok",
    "name": "Flat White",
    "price": 120,
    "category": "drinks",
    "description": "Double shot with steamed milk"
  }
}

Price is in THB. The product syncs to the merchant's storefront on Freedom Mall.

Merchant Onboarding

get_onboarding_status

The onboarding status tool returns a six-item checklist that tracks a merchant's setup progress. This is essential for building AI-guided onboarding flows with the freedom world mcp server.

{
  "name": "get_onboarding_status",
  "arguments": {
    "merchant_id": "roast-bangkok"
  }
}

Response:

{
  "merchant_id": "roast-bangkok",
  "checklist": {
    "identity_verified": true,
    "business_registered": true,
    "products_added": true,
    "payment_configured": false,
    "line_oa_connected": false,
    "google_business_listed": false
  },
  "progress": "3/6",
  "percent_complete": 50
}

The six checklist items:

identity_verified — KYC/identity verification completed or under review

business_registered — merchant app infrastructure provisioned (GitHub repo + Railway service)

products_added — at least one product exists in the catalog

payment_configured — Stripe/Freedom Pay payment processing is active

line_oa_connected — LINE Official Account integration is live

google_business_listed — Google Business Profile is connected

Building an onboarding agent: An AI assistant calls get_onboarding_status, identifies incomplete steps, and walks the merchant through each one conversationally. For example: "I see your payment processing is not configured yet. Let me help you set up your Stripe account."

The server pulls from five Suriya API endpoints in parallel to build this checklist. The response is fast even though it aggregates data from multiple systems.

setup_merchant

Initialize a new merchant and provision their infrastructure:

{
  "name": "setup_merchant",
  "arguments": {
    "business_name": "Roast Bangkok",
    "business_type": "cafe",
    "location": "Silom, Bangkok",
    "owner_name": "Suriya Kittipong"
  }
}

This provisions the merchant's app infrastructure (GitHub repo + Railway service) and returns a merchant_id slug. Full auth registration must be completed via suriya.ai/start.

Phase 2: Wallet and Agent Identity

Four wallet tools are defined in the freedom world mcp server today. They return placeholder responses while the wallet API is under development.

What Is Coming

create_agent_wallet — AI agents will hold their own wallets on the Freedom World platform. They can receive, hold, and spend FDW tokens autonomously.

{
  "name": "create_agent_wallet",
  "arguments": {
    "agent_name": "support-bot-v2"
  }
}

get_wallet_balance — Query any agent or user wallet for current balance and token holdings.

send_payment — Agent-to-agent and agent-to-user payment flows. An AI agent could pay another agent for a service, or distribute rewards to users directly.

{
  "name": "send_payment",
  "arguments": {
    "from_wallet_id": "agent-support-bot",
    "to_wallet_id": "user-12345",
    "amount": 50,
    "currency": "FDW",
    "memo": "Reward for completing survey"
  }
}

register_agent_identity — Register a verified on-chain identity for an AI agent, including declared capabilities. This enables trust scoring and permissioned interactions. A merchant can verify that the agent requesting order data is who it claims to be.

Why Agent Identity Matters

Today, most AI agents are anonymous processes. They authenticate with API keys, but there is no standard way to verify an agent's identity or track its reputation.

Freedom World's Phase 2 brings the same reputation model that works for users to agents:

• Agents accumulate reputation through successful interactions
• Other agents and users can check an agent's standing before trusting it
• Communities can set minimum tier requirements for agent actions

This makes the Freedom World MCP server one of the first AI agent developer tools blockchain platforms to offer verifiable agent identity at the protocol level.

> Key Takeaway: The Freedom World commerce tools give AI agents the ability to operate complete merchant businesses — setup, catalog, orders, payments, and analytics — through MCP tool calls. create_payment_link creates live Stripe PaymentIntents with PromptPay support for Thai merchants, with no custom payment SDK required.

Why Freedom World as Your Agent Economy Layer

The MCP ecosystem is growing fast. Stripe, GoCardless, and Worldpay all have MCP servers for payments. BitGo, Coinbase, and CoinGecko have servers for crypto data. But these are single-purpose tools.

The Freedom World MCP server combines three layers that most agent applications need:

1. Reputation as a Primitive

Most MCP servers assume trust. Freedom World makes trust queryable. Your agent can check a user's standing before processing a high-value transaction, or award points after a successful interaction. Reputation becomes data your agent can read and write — not just a UI badge.

2. Commerce Without Assembly

Instead of wiring together separate MCP servers for payments (Stripe), product management (custom), order tracking (custom), and analytics (custom) — the Freedom World MCP server handles the full merchant lifecycle. One server. One config block. This is model context protocol payments done right.

3. Agent-Native Identity (Phase 2)

No other MCP server blockchain integration is building toward agent wallets and on-chain agent identity. When Phase 2 ships, your agent will not just call tools — it will have its own wallet, its own reputation, and its own verifiable identity.

The bottom line: If you are building AI agents that interact with real users and real money — especially in Southeast Asian markets — the freedom world mcp server gives you the economic infrastructure in a single integration. Read our guide on how blockchain points programs work to understand the underlying economics.

Frequently Asked Questions

What is the Freedom World MCP server?

An open-source Model Context Protocol server that exposes reputation management, commerce, and wallet tools so any MCP-compatible AI assistant (Claude, ChatGPT, Cursor, etc.) can interact with Freedom World communities and Suriya merchant infrastructure on behalf of users.

Which AI clients work with the Freedom World MCP server?

Any MCP-compatible client works — Claude Desktop, Claude Code, ChatGPT (via MCP plugin), Cursor, Windsurf, Cline, and custom agents built with the MCP SDK.

Is the Freedom World MCP server free to use?

Yes. The server is MIT-licensed and free to install. You need a Freedom World access token and optionally a Suriya API key to authenticate against the platform APIs.

What programming language is the MCP server built in?

TypeScript, running on Node.js. The server uses the official MCP SDK and communicates over stdio transport.

Can AI agents make real payments through the MCP server?

Yes. The create_payment_link tool creates live Stripe PaymentIntents supporting card and PromptPay (THB). Amount is specified in the smallest currency unit (satang for THB).

What are the Phase 2 wallet tools?

Phase 2 adds create_agent_wallet, get_wallet_balance, send_payment, and register_agent_identity — enabling AI agents to hold FDW tokens, transact between wallets, and carry verified on-chain identities.

How does the reputation system work?

Freedom World uses a tiered reputation model with seven point types (custom, poster, commenter, chat, shop, topup, mission). Points accumulate into tiers: Bronze (0–99), Silver (100–499), Gold (500–1999), Platinum (2000+). AI agents can query and award points programmatically via the freedom world mcp server.

How is Freedom World different from Stripe's MCP server?

Stripe's MCP server handles payments only. Freedom World's MCP server combines reputation scoring, merchant commerce (orders, products, analytics, payments), merchant onboarding, and upcoming agent wallets with on-chain identity — a full economic layer, not just a payment rail.