The Togetha MCP server: let AI agents query your portfolio

Togetha runs an MCP server - Model Context Protocol, the standard way an AI agent connects to a system and works with real data. Point an agent at it and it can answer questions about your actual portfolio instead of guessing: who is behind on rent, which repairs are still open, whether a tenant has signed.

It is the same workspace your dashboard shows, with the same permissions. An agent can only see what the person who connected it can see.

Endpoint

https://app.togetha.co.uk/api/v2/mcp

It speaks JSON-RPC over HTTP and needs a bearer token carrying the mcp scope. The same token also works against the REST API.

Connecting an agent

Sign in to Togetha and go to Settings -> Developer. Create a token with the mcp scope (add write too if you want the agent to be able to raise tickets and add notes), and copy it - it is only shown once.

That screen also has a Copy config button that gives you the block below with your endpoint already filled in. Paste it into your MCP client and replace the token:

{
  "mcpServers": {
    "togetha": {
      "url": "https://app.togetha.co.uk/api/v2/mcp",
      "headers": {
        "Authorization": "Bearer oat_..."
      }
    }
  }
}

Ask the agent to call whoami first. It will tell you which user and organisation the connection is for, and whether it is allowed to make changes.

If you would rather script it, or you are connecting an agent from another application, the Togetha API guide covers getting a token without the dashboard.

What an agent can read

• list_properties and get_property - properties, units and rooms, with vacancy and for-sale status.
• list_tenancies and get_tenancy - tenancies with rent, dates, address and tenants. get_tenancy also answers "has the tenant signed?", "is the deposit paid?" and how far each tenant has got with their booking form and references.
• list_sales and get_sale - sales with buyer, price, deposit and instalments.
• list_maintenance and get_maintenance - repair tickets, severity, property and assigned contractor.
• list_payments and get_payment - rent and other payments, with an overdue filter for arrears.
• list_expenses - expenses by category, supplier and property.
• list_contacts and get_contact - contractors, buyers and suppliers.
• list_tenants - tenants across the portfolio and the tenancies they are on.
• list_tasks - task boards and their items.
• portfolio_stats - the whole-portfolio snapshot in one call: property count, active and pending tenancies, open maintenance, rent due and collected over 30 days, and who is in arrears.
• search_togetha - fuzzy search across everything at once. The quickest way to turn a name or address into an id.
• query_portfolio - a read-only answer to an ad-hoc question the other tools do not cover.
• search_help_docs - searches these help articles, so an agent can answer "how do I..." properly.

What an agent can change

With the write scope, four more tools:

• create_note - attach a note to a tenancy, property, ticket, sale, payment, tenant or task.
• create_task - add a task to one of your boards.
• create_maintenance_request - raise a repair ticket against a tenancy, or against a property's active tenancy.
• update_maintenance_status - move a ticket to todo, in progress, complete or postponed. Completing one emails the tenant who reported it, exactly as the dashboard does.

Nothing can be archived or deleted over MCP. Those stay in the dashboard, where a person does them deliberately. Connect with only the read scope and the write tools refuse, and say why.

Ready-made prompts

The server ships two prompts you can invoke by name:

• portfolio_review - a portfolio health review covering occupancy, rent collection, arrears and outstanding maintenance.
• arrears_chase - works out who is behind, by how much, and drafts what to say to each of them.

How your data stays scoped

• The token is issued for one organisation, and that is baked into the token itself rather than something the agent sends. It cannot ask for another workspace's data.
• Access is re-checked on every call, so if someone is removed from an organisation their agent stops working straight away rather than when the token eventually expires.
• Every tool applies the organisation filter before anything else.
• Write tools go through the same code the dashboard uses, so activity records, reminders and tenant emails all still happen.

Things worth asking

• "Which tenants are behind on rent, and by how much?"
• "Has everyone signed on the Flat 3 tenancy?"
• "What repairs are still open, worst first?"
• "How much rent did I collect last month against what was due?"
• "Raise a ticket for the boiler at 14 Mill Road and assign it to our usual plumber."

Troubleshooting

• **401 with invalid_token** - the token is missing, expired or revoked. Get a new one from /api/v2/auth/token.
• **403 with insufficient_scope** - the token was not granted mcp. Ask for "scope": "read write mcp" when signing in.
• **403 with no_organisation** - the account no longer has access to the organisation the token was issued for.
• **400 asking for MCP-Session-Id** - the client must call initialize first and echo the session id header back on later calls. Most MCP clients do this for you.

When a single tool fails - a record that is not in your organisation, a missing argument - the agent gets a readable tool error explaining what went wrong, rather than the whole call failing. Take it at face value and adjust the arguments.

To disconnect an agent, revoke its token in Settings -> Developer.