# 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**

```bash
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:

```bash
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](/developers/mcp/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](/developers/mcp/authorization).

## 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?"

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

Then call `community_overview` with one of those ids:

```json
{
  "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.

```json
{
  "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](/developers/mcp/tools): all 14, with arguments and results.
- [Permissions and communities](/developers/mcp/permissions): what each permission allows and who can be granted it.
- [Errors and limits](/developers/mcp/errors-and-limits): what to do when a call is refused.