Quickstart

You need a PorchQ account with a confirmed email address and a role in at least one community. Everything below acts as you, in the communities you choose, so use one where you are allowed to try things.

1. Add the server

Any MCP client that speaks Streamable HTTP and OAuth can connect. The fastest ways:

Claude Code

claude mcp add --transport http porchq https://porchq.com/mcp

Then run /mcp in Claude Code, pick porchq and choose to authenticate. Your browser opens PorchQ.

MCP Inspector, for looking at requests and responses:

npx @modelcontextprotocol/inspector

Choose the Streamable HTTP transport, enter https://porchq.com/mcp and connect. The Inspector runs the sign-in for you.

Claude or ChatGPT: see Clients.

2. Sign in and choose

PorchQ asks you to sign in if you aren’t already, then shows its consent page:

• the app’s name and where its details came from;
• what it will be able to see, in plain words;
• Let the app make changes, ticked by default; untick it so the app can only read;
• your communities, with your role in each; tick the ones the app may reach.

Choose Allow. PorchQ sends you back to the client, which now holds an access token that lasts 60 minutes and a refresh token to get the next one. Details are in Sign-in and tokens.

3. Read something

Ask the client to list PorchQ’s tools; there are 14. Then call property_select without arguments: it lists every community the connection reaches, each with its property_id. In an assistant, simply ask “Which PorchQ communities can you see?”

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "property_select", "arguments": {} }
}

Then call community_overview with one of those ids:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "community_overview", "arguments": { "property_id": "prop_web4k2m9q7x1v8c3n5b6z0a2s4d" } }
}

The result has a short sentence in content and the data in structuredContent: the community, your role and unit, and counts of open requests, announcements, upcoming events, open ballots and documents. It matches the tool’s outputSchema.

Always pass property_id. PorchQ keeps no “current community” for an app. A call without one is answered only when the connection reaches a single community; otherwise PorchQ answers with the list of communities (structuredContent.error.code is property_required) so the app can ask which.

4. Make a change

Filing a maintenance request is a real request. If you’re a resident, the community’s staff are notified, as when you file one in PorchQ.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "maintenance_request_create",
    "arguments": {
      "property_id": "prop_web4k2m9q7x1v8c3n5b6z0a2s4d",
      "title": "Test request from the MCP quickstart",
      "description": "Please ignore: checking the PorchQ MCP connection.",
      "idempotency_key": "quickstart-6f1c2a9e"
    }
  }
}

Send the same request again with the same idempotency_key and PorchQ answers that it was already handled, without filing a second one.

Next

• Tools: all 14, with arguments and results.
• Permissions and communities: what each permission allows and who can be granted it.
• Errors and limits: what to do when a call is refused.