Connecting Claude Code and Codex

Vespy runs a remote Model Context Protocol (MCP) server. Once it’s connected, an AI client like Claude Code or Codex can look up properties, tenants, leases, and reports, and with your permission it can add notes, open maintenance requests, and keep portfolio records up to date.

You don’t need an API key. Each client signs in with your normal Vespy account through a consent screen, so you approve exactly what it can do and can revoke it at any time.

Before you start

• The server URL is:

  https://api.getvespy.com/api/mcp

  You can also copy it from Organization → AI connections in Vespy.

• Who can connect: admins, managers, and staff. Tenant, owner, and vendor portal accounts can’t connect.

• Which organization: a connection always uses the organization your account belongs to.

Claude Code

Add the server from your terminal:

claude mcp add --transport http --scope user vespy https://api.getvespy.com/api/mcp

--scope user makes Vespy available in every project. Use --scope project instead to write it to the repository’s .mcp.json so your team gets it too. That file only holds the URL, and each person still signs in with their own Vespy account.

Then sign in:

1. Start Claude Code with claude, then run /mcp.
2. Select vespy and choose Authenticate.
3. Your browser opens to Vespy. Sign in if asked, review the consent screen, and click Allow access.
4. The browser hands you back to Claude Code, and /mcp shows vespy as connected.

Try asking: “Using Vespy, which leases at Maple Court expire in the next 90 days?”

Codex

Codex CLI

Add the server, then sign in:

codex mcp add vespy --url https://api.getvespy.com/api/mcp

codex mcp login vespy

Codex opens your browser to Vespy. Sign in, review the consent screen, and click Allow access. Run codex mcp list to confirm that vespy is connected.

If you’d rather edit the config yourself, add this to ~/.codex/config.toml and then run codex mcp login vespy:

[mcp_servers.vespy]
url = "https://api.getvespy.com/api/mcp"

Signing in over SSH or on a headless machine

Run codex mcp login vespy --no-browser. Codex prints a sign-in link you can open in any browser. After you click Allow access, the browser lands on a localhost page that won’t load. That’s expected. Copy the full URL from the address bar and paste it back into the terminal.

Codex app and IDE extension

Open the MCP server settings and add a Streamable HTTP server with the URL above. Then choose Authenticate and approve the consent screen.

Claude on the web and desktop

In Claude, open Settings → Connectors and add a custom connector with the URL above. Choose Connect, then sign in and approve the consent screen. Hosted Claude returns to claude.ai after you approve, so you won’t see the local-application warning.

Review the consent screen

Every client lands on the same Vespy-branded consent screen. Before you click Allow access, check that:

• Signed in as shows your Vespy account and Organization shows the right organization.
• Returns to matches where you started. A 127.0.0.1 or localhost address means Claude Code or Codex on your own computer. Vespy shows a warning for these callbacks. Continue only if you started the connection yourself.

The client asks for these permissions:

Permission	What it allows
Read portfolio operations	Search and read properties, units, tenants, leases, charges, payments, vendors, maintenance, conversations, and financial reports.
Add internal notes	Add notes to records. Notes are always internal and never visible to tenants or vendors.
Manage maintenance requests	Open maintenance requests with a suitable vendor and update them. Assignment and status changes notify the vendor and tenant as usual.
Create and update portfolio records	Create and update properties, units, tenants, vendors, owners, buildings, floors, and tenant contacts. Requires an admin or manager.

Select Grant read access only to allow reads and nothing else. A client can never receive more access than it asked for, or more than your role allows. If your role changes or your account is deactivated, the connection follows that change right away.

What a connected client can’t do

It can’t delete records, change leases or accounting, send invitations, or message tenants and vendors. The only outside notifications it can cause are the usual ones when a maintenance request’s assignment or status changes. Your Vespy password is never shared with the client. Every change it makes is recorded under your name.

Manage and revoke connections

Go to Organization → AI connections to see each connection’s client, permissions, when it was last used, and when it expires. Click Revoke to cut off access immediately. Admins can see and revoke every connection in the organization. Everyone else sees only their own.

A connection lasts 30 days from when you approve it. After that, your client asks you to sign in again.

Troubleshooting

“This connection request is unavailable or expired.” A consent screen is valid for 10 minutes and can be used only once. Start again from your client by running /mcp in Claude Code or codex mcp login vespy in Codex.

The client can’t make changes it should be able to. Check whether you chose Grant read access only, and whether your role allows the change. Creating and updating portfolio records requires an admin or manager. To change permissions, revoke the connection and sign in again.

Reconnecting from scratch. In Claude Code, run /mcp, select vespy, and clear its authentication. In Codex, run codex mcp logout vespy. Then sign in again.

Codex can’t register with Vespy. Retry with codex mcp login vespy --oauth-client-registration dcr.

Afterwards

• Use the AI portfolio assistant. The built-in assistant answers the same questions without leaving Vespy.
• Add team members. Roles decide what each person’s connections can do.