MCP Object Specification

Overview

The MCP Context Object (MCO) is a signed, structured payload that encapsulates all contextual data an LLM or agent needs to operate in a personalized, decentralized, and verifiable way.

It is the standard communication format between context providers (wallets, smart contracts, DIDs) and context consumers (LLMs, AI agents).

---

Full JSON Schema (Draft v0.1)

{
    "version": "0.1",
    "subject": "did:pkh:eth:0x123abc...",
    "timestamp": 1728323900,
    "permissions": ["read.dao", "read.tokens", "read.nft"],
    "context": {
        "wallet": {
            "address": "0x123abc...",
            "chain_id": 1,
            "token_balances": [
                {
                    "symbol": "DAI",
                    "amount": "124.35",
                    "contract": "0x6b175474e89094c44da98b954eedeac495271d0f"
                }
            ],
            "nfts": [
                {
                    "collection": "Zorb",
                    "token_id": "1234",
                    "contract": "0xabcd..."
                }
            ]
        },
        "dao": {
            "memberships": [
                {
                    "dao_name": "MetaDAO",
                    "member_since": "2023-04-15",
                    "roles": ["voter", "delegate"],
                    "voting_power": 342
                }
            ],
            "recent_votes": [
                {
                    "proposal_id": "proposal_42",
                    "vote": "yes",
                    "timestamp": 1723122900
                }
            ]
        },
        "profile": {
            "ens": "user.eth",
            "lens": "@user.lens",
            "farcaster": "fid:12345"
        }
    },
    "proof": {
        "type": "EIP712Signature",
        "signer": "0x123abc...",
        "signature": "0xdeadbeef...",
        "domain": {
            "name": "MCP3 Gateway",
            "version": "1.0",
            "chainId": 1
        }
    }
}

---

Field Descriptions

Field	Type	Description
version	string	Protocol version.
subject	string	DID or Wallet address of the user.
timestamp	number	UNIX timestamp of when context was generated.
permissions	string[]	Allowed context scopes (per user consent).
context.wallet	object	Wallet-specific data, tokens, NFTs.
context.dao	object	DAO-related activity (roles, votes).
context.profile	object	Off-chain social data (ENS, Lens, Farcaster).
proof	object	Cryptographic attestation of authenticity.

---

Proof Strategies

• EIP712Signature: Signed using the user's wallet. Standard for typed data in Ethereum.

• zkProof (optional): Zero-knowledge attestation of claims (e.g. age > 18, DAO member without revealing address).

• SIWE: Context can be included as a claim in a SIWE session.

---

Context Mutability

Context Field	Mutable?	Source
wallet.token_balances	✅	On-chain or external indexer
dao.recent_votes	✅	Snapshot / contract API
profile.ens	❌	On-chain, stable
permissions	✅	User-controlled

---

Best Practices

• 🧾 Always timestamp the MCO to avoid replay attacks.

• 🔒 MCO must be signed or ZK-proven before being passed to an LLM.

• 📦 Context objects can be stored IPFS-side for caching, but always verify the signature before use.

• ⚠️ Don’t pass sensitive data in plain text without user consent.

---

Example Usage

function respondWithContext(mco) {
    verifySignature(mco.proof)
    const userENS = mco.context.profile.ens
    const daoCount = mco.context.dao.memberships.length
    return `Hello ${userENS}, you are a member of ${daoCount} DAOs.`
}

---

Future Extensions

• Support for Verifiable Credentials (VCs) using W3C standards

• Modular support for chain-agnostic context (Solana, Starknet)

• Integration with decentralized context brokers (e.g. Ceramic, SpruceID)

==========

🛠️ Context API Reference

The MCP3 Context API enables clients (LLMs, agents, dApps) to request, verify, and utilize context objects securely and efficiently.

---

🧵 Base URL

https://api.mcp3.app/v1

---

🔄 Endpoints

GET /context

Retrieve a signed, structured MCP Context Object (MCO) for a user wallet or DID.

Query Parameters:

Param	Type	Required	Description
subject	string	✅	The wallet address or DID of the user
scopes	string[]	✅	Requested context scopes (e.g. ["read.dao", "read.tokens"])
format	string	❌	Output format: "json" (default) or "eip712"

Example Request:

GET /context?subject=did:pkh:eth:0xabc...&scopes=read.dao,read.tokens

Example Response:

{
    "version": "0.1",
    "subject": "did:pkh:eth:0xabc...",
    "timestamp": 1728323900,
    "permissions": ["read.dao", "read.tokens"],
    "context": {
        "wallet": {...},
        "dao": {...}
    },
    "proof": {
        "type": "EIP712Signature",
        "signature": "0xdeadbeef...",
        "signer": "0xabc..."
    }
}

---

POST /verify

Verify the authenticity of an MCO using EIP-712 signature or ZK proof.

Body:

{
    "context": { ... },
    "proof": { ... }
}

Response:

{
    "valid": true,
    "signer": "0xabc...",
    "method": "EIP712Signature"
}

---

POST /sign

Request the MCP gateway to generate a signed context on behalf of a subject (via delegated key).

Body:

{
    "subject": "did:pkh:eth:0xabc...",
    "scopes": ["read.dao", "read.tokens"],
    "delegated_signer_key": "api-key-xyz"
}

Response:

{
    "mco": {
        "context": { ... },
        "proof": {
            "type": "EIP712Signature",
            "signer": "0xdelegate...",
            "signature": "0x..."
        }
    }
}

---

GET /metadata

Returns schema metadata, supported proof types, and permission scopes.

Example Response:

{
    "supported_versions": ["0.1"],
    "proof_types": ["EIP712Signature", "zkProof"],
    "scopes": [
        "read.dao", "read.tokens", "read.profile",
        "read.attestations", "read.nft"
    ]
}

---

🔐 Authentication

All POST endpoints require API key or signed request headers.

Public GET /context requests are allowed in read-only mode for public data.

Authorization: Bearer YOUR_API_KEY

---

⚠️ Error Codes

Code	Meaning
400	Invalid parameters
401	Unauthorized / Missing signature
403	Scope not permitted
404	Subject not found
500	Internal MCP engine error

---

🚀 SDK Support

Official SDKs:

• @mcp3/sdk-js (Node.js, browser)

• mcp3-python (coming soon)

REST-compatible with Postman & cURL

Example (JS):

import { getContext } from '@mcp3/sdk-js'

const mco = await getContext({
    subject: "0xabc...",
    scopes: ["read.dao", "read.tokens"]
})

---

🧩 GraphQL Preview (Optional)

If enabled:

query {
    context(subject: "0xabc...") {
        dao { memberships { dao_name } }
        wallet { token_balances { symbol amount } }
    }
}