0%

MCP - End User Getting Started Guide

MCP Server - End User Getting Started Guide

This guide walks you through connecting to Prophia's MCP server from an MCP client such as Claude Desktop, Claude Code, Cursor, or any other MCP-compatible tool. There are two ways to connect: OAuth (recommended) or API Key.

What is MCP?

The Model Context Protocol (MCP) lets AI assistants like Claude access your Prophia data directly — accounts, buildings, leases, and documents. Instead of copy-pasting data, your AI assistant can query Prophia in real time.

What You Need

  • A Prophia user account

  • Your organization's account name (the URL slug for your Prophia account — ask your admin if unsure)

  • An MCP-compatible client application

Option 1: Connect with OAuth (Recommended)

OAuth lets you authenticate using your organization's existing single sign-on (Okta, Azure AD, Auth0, etc.). This is the most secure option and doesn't require managing API keys.

Before individual users can connect, your IT team needs to set up OAuth once for your organization — see Setting Up OAuth for Your Organization below. Once that's done, follow the client-specific instructions here.

Claude Desktop

  1. Open Claude Desktop settings

  2. Go to the MCP Servers section

  3. Add a new server with this configuration:

{ "mcpServers": { "prophia": { "type": "streamable-http", "url": "https://api.prophia.com/mcp/v1/{your-account-name}" } } }

  1. Replace {your-account-name} with your organization's Prophia account name

  2. Save and restart Claude Desktop

  3. When you first use a Prophia tool, a browser window will open for you to sign in with your corporate credentials

  4. After signing in, Claude will have access to your Prophia data

Claude Code (CLI)

Add the server using the CLI:

claude mcp add prophia --transport http https://api.prophia.com/mcp/v1/{your-account-name}

On first use, a browser window will open for OAuth authentication.

Cursor

  1. Open Cursor settings

  2. Navigate to the MCP section

  3. Add a new server:

    • Name: Prophia

    • Type: Streamable HTTP

    • URL: https://api.prophia.com/mcp/v1/{your-account-name}

  4. On first use, you'll be prompted to authenticate via your browser

Other MCP Clients

For any MCP client that supports Streamable HTTP transport, use:

  • Server URL: https://api.prophia.com/mcp/v1/{your-account-name}

  • Transport: Streamable HTTP

  • Auth: The client will automatically discover OAuth endpoints and guide you through login

Setting Up OAuth for Your Organization

This is a one-time setup performed by your organization's IT / identity-provider admin. Once complete, all Prophia users at your company can connect their MCP clients via SSO without managing API keys.

Prophia supports any standards-compliant OIDC identity provider (Okta, Azure AD / Entra ID, Auth0, Google Workspace, Keycloak, etc.).

Step 1: Create an OIDC Application in Your Identity Provider

In your IdP's admin console, create a new OIDC / OAuth2 application for Prophia with the following settings:

  • Application type: Web application (confidential or public — either works)

  • Grant type: Authorization Code

  • Redirect URI: https://yosemite-api.prophia.com/mcp/auth/login/oauth2/code/{your-account-name}

  • Scopes: openid, profile, email

  • ID token claims: Must include the user's email

Note on the redirect URI host: The customer-facing MCP URL uses api.prophia.com, but the OIDC redirect URI must be registered as yosemite-api.prophia.com — that is the canonical host the redirect resolves to after DNS. Register it exactly as shown above.

Email matching is required. The email claim returned by your IdP must match the email on an existing Prophia user account. Users whose corporate email doesn't match a Prophia user will be rejected with "access denied."

Step 2: Send the Following Information to Prophia

Once your OIDC app is created, send these values to your Prophia contact or Prophia Support:

  • Issuer URI: The base URL of your IdP's OIDC discovery document, without /.well-known/openid-configuration (e.g., https://acme.okta.com/oauth2/default)

  • Client ID: The OAuth2 client ID issued by your IdP for this application (e.g., 0oa1b2c3d4e5f6g7h8i9)

  • Client Secret (optional): Only if your IdP requires client_secret_basic authentication. If your app is registered as a public client with PKCE, leave this out.

Prophia uses these values to register your IdP for your account. Once Prophia confirms setup is complete, any user at your organization can follow the client-specific instructions above to connect.

Step 3: Verify

Ask a Prophia user at your org to connect their MCP client to https://api.prophia.com/mcp/v1/{your-account-name}. They should be redirected to your IdP's login page, and after authenticating they should be able to use Prophia tools from their AI assistant.

If login succeeds but the user gets "access denied," double-check that the email returned by your IdP matches their Prophia user email exactly.

Option 2: Connect with an API Key

If your MCP client doesn't support OAuth, or you prefer a simpler setup, you can use an API key.

⚠️ Claude Desktop does not currently support an API key connection to our type of MCP. The OAuth setup is required for Claude Desktop.

Step 1: Generate an API Key

Account Level API Key:

  1. Log into the Prophia web application

  2. Navigate to your user settings / API tokens page

  3. Create a new token with a descriptive name (e.g., "Claude Desktop MCP")

  4. Copy the API key immediately — it will only be shown once

If you don't see an API tokens option, or the generated key doesn't work against MCP, contact your Prophia administrator.

⚠️ Account level API keys provide Admin level permission to your data.

User API Key:

An API key scoped to a particular user and account can be generated for any user in your organization. These keys will provide the same access that user has in the Prophia application. This can be done by making a request through your Prophia administrator.

Step 2: Configure Your MCP Client

Claude Code:

claude mcp add prophia \ --transport http \ --header "Authorization: Bearer {your-api-key}" \ https://api.prophia.com/mcp/v1/{your-account-name}

Cursor / Other Clients — use your client's MCP configuration to set:

  • URL: https://api.prophia.com/mcp/v1/{your-account-name}

  • Transport: Streamable HTTP

  • Header: Authorization: Bearer {your-api-key}

API Key Security Tips

  • API keys grant access to your Prophia data — treat them like passwords

  • Use a unique key for each application

  • Revoke keys you no longer use from your user settings page

  • Keys are scoped to your Prophia account

Available Tools

Once connected, your AI assistant will have access to these tools:

Accounts & Properties:

  • list_accounts — List all Prophia accounts you have access to

  • get_account — Get details of a specific account

  • recent_changed_leases — List leases whose documents were updated within a date range

  • list_properties_for_account — List all properties in an account

  • list_buildings_for_account — List all buildings in an account

  • list_buildings_for_property — List all buildings for a specific property

  • get_building — Get details of a specific building

  • get_property — Get details of a specific property

Leases:

  • get_lease — Get details of a specific lease

  • list_leases_for_building — List all leases in a building

  • list_leases_for_property — List all leases for a property

  • get_lease_doc_list — List all documents attached to a lease

Documents & Search:

  • get_doc_pages — Get all pages of a lease document

  • search_text_bounding_boxes — Find specific text on a document page

  • smart_search_account — Search across all documents in an account

  • smart_search_property — Search across all documents in a property

  • smart_search_lease — Search across all documents in a lease

  • smart_search_doc — Search within a specific document

Example Prompts

Once connected, try asking your AI assistant:

  • "List all my Prophia accounts"

  • "Show me the buildings in {account name}"

  • "What leases are in {building name}?"

  • "Find all rent escalation clauses in the documents for {lease}"

  • "Search for 'force majeure' across all documents in {property}"

  • "What leases had document changes in the last 30 days?"

Troubleshooting

"Authentication required" error

  • OAuth: Try disconnecting and reconnecting the MCP server to re-authenticate

  • API key: Verify your key is correct and hasn't been revoked

"Access denied" error

  • Your Prophia user account may not have access to the requested account or building

  • For OAuth: the email returned by your IdP may not match your Prophia user email

  • Contact your Prophia administrator to check your permissions

MCP server not responding

  • Verify the URL is correct: https://api.prophia.com/mcp/v1/{your-account-name}

  • Check that your account name matches exactly (it's case-sensitive)

  • Ensure your organization has MCP access enabled

OAuth login opens but fails

  • Make sure your corporate email matches your Prophia user account email

  • Check with your IT team that the Prophia OIDC integration is configured in your identity provider

Need help?

Contact your Prophia administrator or reach out to Prophia Support.

0%