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
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
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:
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.tokensExample 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
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 } }
}
}Last updated