Skip to content
English - United Kingdom
Contact us
  • There are no suggestions because the search field is empty.

Using the Konquest MCP Server with Claude Code

Connect your Konquest account to Claude Code using the Konquest MCP (Model Context Protocol) server. Once set up, you can manage placements, beneficiaries, timesheets, schemes, and more - simply by describing what you need in plain language. Authentication is handled securely through Auth0 using your existing Konquest credentials.

Before you begin

Make sure you have the following:

  • Claude Code installed and signed in. Get Claude Code →
  • An active Konquest user account (you'll sign in with your usual credentials during setup)

Step 1: Add the Konquest MCP server

Run the following command in your terminal:

claude mcp add --transport http konquest https://mcp.konquest.io/mcp \
--callback-port 8080 \
--client-id SHbYiiQcjZYXYAaerp08sXIAK7sV6QmI

What each part does:

Flag Value Purpose
--transport http — Konquest MCP uses streamable HTTP rather than stdio
--callback-port 8080 Pins the OAuth callback to http://localhost:8080/callback, which is pre-registered with Auth0. Without this, Auth0 will reject the callback.
--client-id SHbYiiQcjZYXYAaerp08sXIAK7sV6QmI Identifies the Claude Code application to Auth0 so it can issue the correct token

Note: The name konquest in the command above is just a label — you can use any name you'll recognise when running /mcp.

Step 2: Sign in with your Konquest credentials

The first time Claude Code connects to the server, a browser window will open and take you to the Auth0 sign-in page. Sign in with your usual Konquest credentials.

Once approved, you'll be redirected back to localhost:8080 and your terminal will confirm the connection is active.

To check the connection at any time:

claude mcp list

Or, inside a Claude Code session, type /mcp to see the status of all connected servers.

Using Konquest in Claude Code

Once connected, just describe what you want to do in plain language. Claude Code will call the right tool automatically. For example:

  • "List all my schemes"
  • "Show me placements for source ID 12345"
  • "Add a timesheet entry for user X this week"
  • "Enrol user Y on the Goodall Brazier scheme"

Troubleshooting

HTTP 401 error after authenticating

Your token isn't being accepted. Remove the server and re-add it to start a fresh authentication flow:

claude mcp remove konquest
claude mcp add --transport http konquest https://mcp.konquest.io/mcp \
--callback-port 8080 \
--client-id SHbYiiQcjZYXYAaerp08sXIAK7sV6QmI

The browser hangs on localhost:8080 during sign-in

Another process on your machine is using port 8080. Stop the conflicting process and try again, or contact us to arrange an additional callback port.

"Got new credentials, but reconnecting failed"

This is usually caused by a stale cached token. Remove and re-add the server as shown above.

Still having trouble?

Contact our support team with the exact error message shown in /mcp and we'll help you get connected.