MCP from A to Z. How an AI assistant connects to your data, and how to build one.

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{
     "protocolVersion":"2025-06-18","capabilities":{},
     "clientInfo":{"name":"claude-code","version":"1.0"}}}

← {"jsonrpc":"2.0","id":1,"result":{
     "protocolVersion":"2025-06-18",
     "capabilities":{"tools":{"listChanged":false}},
     "serverInfo":{"name":"paypedia","version":"1.0.0"}}}

→ {"jsonrpc":"2.0","method":"notifications/initialized"}      ← no id: NO response

→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[
     {"name":"iban_check","description":"Validates one or more IBANs…",
      "inputSchema":{"type":"object","properties":{"input":{"type":"string"}},
                     "required":["input"],"additionalProperties":false}} ]}}

→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
     "name":"iban_check","arguments":{"input":"FR7630006000011234567890189"}}}
← {"jsonrpc":"2.0","id":3,"result":{
     "content":[{"type":"text","text":"## FR76 3000 6000 …\n**VALID** · France (FR)…"}],
     "isError":false}}

{
  name: 'bank_resolve',                       // stable identifier, snake_case
  title: 'Resolve a bank code',               // human-readable label (optional)
  description:
    "Returns a bank's name and BIC from its national bank code (the one " +
    "embedded in the IBAN) and its country. Registry of ~22,900 codes in 44 countries. " +
    "Call this when you have a bank code (e.g., 30004 in France) but do not know " +
    "which institution it belongs to.",        // ← THIS is what triggers the call
  inputSchema: {
    type: 'object',
    properties: {
      country:  { type: 'string', maxLength: 8,  description: 'ISO 3166-1 alpha-2 country code, e.g., "FR", "DE", "ES".' },
      bankCode: { type: 'string', maxLength: 16, description: 'National bank code, e.g., "30004".' },
    },
    required: ['country', 'bankCode'],
    additionalProperties: false,
  },
  run: async (args) => '…the text handed to the model…',
}

const TOOLS = [{
  name: 'sum',
  description: 'Adds two numbers. Call this for any addition.',
  inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } },
                 required: ['a', 'b'], additionalProperties: false },
  run: ({ a, b }) => `${a} + ${b} = ${Number(a) + Number(b)}`,
}]

const send = (m) => process.stdout.write(JSON.stringify(m) + '\n')   // stdout = protocol
const log  = (m) => process.stderr.write(m + '\n')                   // stderr = logs

let buf = ''
process.stdin.setEncoding('utf8')
process.stdin.on('data', (chunk) => {
  buf += chunk
  let nl
  while ((nl = buf.indexOf('\n')) >= 0) {
    const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1)
    if (!line) continue
    let msg
    try { msg = JSON.parse(line) } catch { send({ jsonrpc: '2.0', id: null,
      error: { code: -32700, message: 'Invalid JSON' } }); continue }
    if (!msg || typeof msg !== 'object') continue      // 'null' is valid JSON
    const isRequest = msg.id !== undefined && msg.id !== null

    if (msg.method === 'initialize') {
      send({ jsonrpc: '2.0', id: msg.id, result: {
        protocolVersion: msg.params?.protocolVersion ?? '2025-06-18',
        capabilities: { tools: {} },
        serverInfo: { name: 'example', version: '1.0.0' } } })
    } else if (msg.method === 'tools/list' && isRequest) {
      send({ jsonrpc: '2.0', id: msg.id, result: {
        tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) } })
    } else if (msg.method === 'tools/call' && isRequest) {
      const tool = TOOLS.find((t) => t.name === msg.params?.name)
      if (!tool) return send({ jsonrpc: '2.0', id: msg.id,
        error: { code: -32602, message: 'Unknown tool' } })
      try {
        send({ jsonrpc: '2.0', id: msg.id,
          result: { content: [{ type: 'text', text: tool.run(msg.params.arguments ?? {}) }] } })
      } catch (e) {                                     // EXECUTION error: goes in the result
        send({ jsonrpc: '2.0', id: msg.id,
          result: { content: [{ type: 'text', text: 'Error: ' + e.message }], isError: true } })
      }
    } else if (isRequest) {
      send({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'Method not found' } })
    }
    // no id: it is a notification → reply with NOTHING
  }
})
log('ready')

{
  "mcpServers": {
    "paypedia": {
      "command": "node",
      "args": ["/path/to/paypedia/mcp/dist/paypedia-mcp.mjs"],
      "env": { "PAYPEDIA_ROOT": "/path/to/paypedia" }
    }
  }
}