AutoPostcode

AutoPostcode MCP setup and tool reference

Connect an AI agent to AutoPostcode over Streamable HTTP. Read public product facts, verify a scoped connection and look up UK postcodes.

View Markdown

Connect over Streamable HTTP

Use https://autopostcode.com/mcp as a remote Streamable HTTP URL. The endpoint returns JSON over POST. The GET event stream, session deletion and legacy SSE transport are unavailable.

Public facts require no account or credential. For authenticated tools, the workspace owner creates a website-bound agent key in Dashboard → API & MCP. Choose connection:read for the free check, and add postcode:read only when the agent may spend credits on lookups.

Store the one-time secret as AUTOPOSTCODE_AGENT_KEY in the executing client host’s secret manager. Pass it as Authorization: Bearer. A remote or containerised client needs the value provisioned there. Keep the value out of source, prompts, chat, URLs and logs.

Run get_connection_status first. It should return connected=true, expires_at in UTC and the authorised scopes. Billing readiness is checked separately at lookup. For rotation, install and test a replacement key before revoking the old one.

Coding agent setup prompt
text
Integrate AutoPostcode for the task I describe. Read https://autopostcode.com/developers.md and follow its current contracts.

Start with public product facts. Choose only the permission needed. For an authenticated MCP smoke check, use get_connection_status with a connection:read key. It costs zero credits.

Ask me to configure AUTOPOSTCODE_AGENT_KEY in the client host's secret storage, including on a remote machine if that is where the client runs. Never ask for the value in chat, source, prompts or logs.

Show me the transport, tool, intended scope and expected result. Wait for my approval before consuming credits or sending customer information. For a lookup retry, reuse the same retry UUID. Report the X-Request-Id and redact secrets and customer data.
Initialize (cURL)
bash
curl -i 'https://autopostcode.com/mcp' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"manual-check","version":"1.0.0"}}}'
Acknowledge initialization (cURL)
bash
curl -i 'https://autopostcode.com/mcp' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'
List tools (cURL)
bash
curl -i 'https://autopostcode.com/mcp' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
Authenticated first read (cURL)
bash
curl -i 'https://autopostcode.com/mcp' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $AUTOPOSTCODE_AGENT_KEY" \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_connection_status","arguments":{}}}'
Authenticated first read (PowerShell)
powershell
$headers = @{ Accept = 'application/json, text/event-stream'; Authorization = "Bearer $env:AUTOPOSTCODE_AGENT_KEY" }
$body = '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_connection_status","arguments":{}}}'
Invoke-RestMethod -Method Post -Uri 'https://autopostcode.com/mcp' -Headers $headers -ContentType 'application/json' -Body $body

Client setup and verification

Choose a dedicated client guide for setup steps, credential requirements and the exact result of the live test for that client.

VS Code — configure a remote HTTP server with secure input for the Bearer header. Target get_connection_status. A real connection is unverified.

VS Code .vscode/mcp.json
json
{
  "inputs": [
    {
      "id": "autopostcode-key",
      "type": "promptString",
      "description": "AutoPostcode agent key",
      "password": true
    }
  ],
  "servers": {
    "autopostcode": {
      "type": "http",
      "url": "https://autopostcode.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:autopostcode-key}"
      }
    }
  }
}

MCP tools

tools/list returns current tool names and schemas without exposing account data.

Read public product facts

get_product_facts

Get public UK data coverage, published pricing and AutoPostcode integration links.

Access — Anonymous. Free

Returns public JSON without workspace data. Repeat freely under normal use.

MCP request
bash
curl -i 'https://autopostcode.com/mcp' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_product_facts","arguments":{}}}'
Arguments schema
json
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Structured result schema
json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "summary": {
      "type": "string"
    },
    "data_source": {
      "type": "string"
    },
    "response_time": {
      "type": "string"
    },
    "coverage": {
      "type": "object",
      "properties": {
        "addresses": {
          "type": "string"
        },
        "postcodes": {
          "type": "string"
        },
        "region": {
          "type": "string"
        }
      },
      "required": [
        "addresses",
        "postcodes",
        "region"
      ]
    },
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "name",
          "description",
          "endpoint"
        ]
      }
    },
    "billing": {
      "type": "object",
      "properties": {
        "unit": {
          "type": "string"
        },
        "autocomplete_rule": {
          "type": "string"
        },
        "trial_days": {
          "type": "integer",
          "minimum": 0
        },
        "annual_discount_pct": {
          "type": "integer",
          "minimum": 0
        },
        "currency": {
          "type": "string"
        },
        "vat": {
          "type": "string"
        },
        "plans": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "monthly_price_gbp": {
                "type": "number"
              },
              "monthly_lookups": {
                "type": "integer",
                "minimum": 0
              },
              "per_lookup_gbp": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "required": [
              "name",
              "monthly_price_gbp",
              "monthly_lookups",
              "per_lookup_gbp"
            ]
          }
        },
        "credit_packs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "price_gbp": {
                "type": "number"
              },
              "credits": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "name",
              "price_gbp",
              "credits"
            ]
          }
        }
      },
      "required": [
        "unit",
        "autocomplete_rule",
        "trial_days",
        "annual_discount_pct",
        "currency",
        "vat",
        "plans",
        "credit_packs"
      ]
    },
    "price_beat_guarantee": {
      "type": "string"
    },
    "wordpress_plugin": {
      "type": "object",
      "properties": {
        "version": {
          "type": "string"
        },
        "download": {
          "type": "string"
        },
        "platforms": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "download",
        "platforms"
      ]
    },
    "developer": {
      "type": "object",
      "properties": {
        "openapi": {
          "type": "string"
        },
        "docs": {
          "type": "string"
        },
        "markdown": {
          "type": "string"
        },
        "mcp": {
          "type": "string"
        },
        "auth": {
          "type": "string"
        }
      },
      "required": [
        "openapi",
        "docs",
        "markdown",
        "mcp",
        "auth"
      ]
    },
    "contact": {
      "type": "string"
    }
  },
  "required": [
    "name",
    "url",
    "summary",
    "data_source",
    "response_time",
    "coverage",
    "products",
    "billing",
    "price_beat_guarantee",
    "wordpress_plugin",
    "developer",
    "contact"
  ]
}

Check a workspace connection

get_connection_status

Check that an AutoPostcode agent key is active and read its scopes and expiry.

Access — connection:read. Free

Returns connected=true, current scopes and UTC expiry. Billing readiness is evaluated separately for a lookup.

MCP request
bash
curl -i 'https://autopostcode.com/mcp' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $AUTOPOSTCODE_AGENT_KEY" \
  --data '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_connection_status","arguments":{}}}'
Arguments schema
json
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}
Structured result schema
json
{
  "type": "object",
  "properties": {
    "connected": {
      "type": "boolean"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "connection:read",
          "postcode:read"
        ]
      }
    },
    "expires_at": {
      "type": "string"
    }
  },
  "required": [
    "connected",
    "scopes",
    "expires_at"
  ]
}

Look up a UK postcode

lookup_postcode

Return address candidates for one full UK postcode. A matched lookup consumes one credit. Use the same UUID only when retrying the same lookup.

Access — postcode:read. 1 credit for a match, zero for a miss or a replay within 24 hours.

200 JSON-RPC success can contain an empty address array. No pagination. The fallback source can return up to 100 results. Offer manual entry on a miss. Reuse the retry UUID only for the same postcode and credential. Addresses are resolved again on retries. Application failures set isError=true.

MCP request
bash
curl -i 'https://autopostcode.com/mcp' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $AUTOPOSTCODE_AGENT_KEY" \
  --data '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"lookup_postcode","arguments":{"postcode":"SW1A 1AA","retry_id":"02aafd5f-8909-49cb-ad09-0fd6b57d5325"}}}'
Arguments schema
json
{
  "type": "object",
  "properties": {
    "postcode": {
      "type": "string",
      "minLength": 5,
      "maxLength": 12
    },
    "retry_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "postcode",
    "retry_id"
  ],
  "additionalProperties": false
}
Structured result schema
json
{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "minimum": 0
    },
    "addresses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "postcode": {
            "type": "string"
          },
          "company": {
            "type": "string"
          },
          "line1": {
            "type": "string"
          },
          "line2": {
            "type": "string"
          },
          "line3": {
            "type": "string"
          },
          "dependent_locality": {
            "type": "string"
          },
          "town": {
            "type": "string"
          },
          "county": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "line1_full": {
            "type": "string"
          },
          "formatted_address": {
            "type": "string"
          }
        },
        "required": [
          "postcode",
          "company",
          "line1",
          "line2",
          "line3",
          "dependent_locality",
          "town",
          "county",
          "country",
          "line1_full",
          "formatted_address"
        ]
      }
    },
    "credits_charged": {
      "type": "integer",
      "minimum": 0
    },
    "replayed": {
      "type": "boolean"
    }
  },
  "required": [
    "count",
    "addresses",
    "credits_charged",
    "replayed"
  ]
}