Skip to content
v0.5.1GitHub

Using

MCP with Claude

applies to v0.5.1

This page connects Claude Code and Claude Desktop to a LuraDB server as MCP clients. For the protocol, the list of tools and the permissions, see MCP server; this page does not repeat them. The setup of the Claude side follows the public guides of Anthropic, listed at the end with the date they were read; their menus and labels can change.

Before you start

Section titled “Before you start”

On the LuraDB side, switch the MCP server on and restart, see MCP server:

[mcp]
enabled = true

Then choose how the client signs in:

  • An API key as a Bearer token. The key is stored in the configuration of the client. Create a user for it with the permissions it needs and no more, see Security; mcp.read_only true keeps every MCP tool from changing data.
  • OAuth. The user signs in once on a LuraDB page, and the client stores tokens, not the key. It needs mcp.oauth_enabled and mcp.public_url, see MCP server.

Which Claude application reaches your server depends on where the connection starts:

Client Connects from A LuraDB on 127.0.0.1 Signs in with
Claude Code Your computer Works. A header with the key, or OAuth through /mcp.
Claude Desktop, custom connector Anthropic’s cloud Does not work: the server must be reachable from the public internet. OAuth, or fixed request headers.
Claude Desktop, mcp-remote in the config file Your computer Works. A header with the key, or OAuth in the bridge.

For a custom connector the URL must be a public https:// address, for example a reverse proxy with a certificate in front of the MCP port, with mcp.public_url set to that address.

The examples use the URL http://127.0.0.1:3100/mcp and a key in $LURADB_KEY.

Claude Code

Section titled “Claude Code”

Claude Code adds an MCP server with claude mcp add. For a server reachable over HTTP, the transport is http.

With an API key

Section titled “With an API key”

Pass the key as a header:

Terminal window
claude mcp add --transport http luradb http://127.0.0.1:3100/mcp \
  --header "Authorization: Bearer $LURADB_KEY"

luradb is the name Claude Code shows. The server is stored for the current project by default; --scope user makes it available in all your projects, and --scope project writes it to .mcp.json in the project, which is shared through version control, so keep a key out of that file. Check the entry with:

Terminal window
claude mcp list
claude mcp get luradb

Inside a Claude Code session, /mcp shows the status of the connected servers.

With OAuth

Section titled “With OAuth”

Add the server without a header:

Terminal window
claude mcp add --transport http luradb https://db.example.com:3100/mcp

Then type /mcp in a Claude Code session and follow the steps in your browser to log in. The browser shows the sign-in page of LuraDB:

Sign in to LuraDB


<client name> asks for access to this LuraDB with the permissions of your API key;
it will be sent back to <address>.


API key  [ ••••••••••••• ]
[ Allow access ]  [ Deny ]

Type your API key and choose Allow access; the key goes to LuraDB, not to Claude Code. The name of the client and the address in the sentence are those the client registered with LuraDB as its redirect address; for Claude Code the address is on localhost. If your browser does not open by itself, copy the address that Claude Code shows and open it by hand. Clear authentication in the /mcp menu revokes access.

Removing the server

Section titled “Removing the server”
Terminal window
claude mcp remove luradb

Claude Desktop

Section titled “Claude Desktop”

Claude Desktop has two ways to reach a server. A custom connector is made in the application and connects from Anthropic’s cloud. A local entry in the configuration file starts a small program on your computer that connects to the server.

As a custom connector

Section titled “As a custom connector”

The server must be reachable over the public internet from Anthropic’s IP ranges; a server on a private network, behind a VPN or behind a firewall does not connect unless those addresses are allowed. Use https. The steps, as Anthropic’s guide gives them for the plans Pro and Max (on Team and Enterprise plans an owner adds the connector under Organization settings first):

  1. Go to Customize > Connectors.
  2. Click + Add, then Add custom connector.
  3. Enter a name, for example LuraDB. This is what you see in the list of connectors.
  4. Enter the remote MCP server URL, for example https://db.example.com:3100/mcp, and click Continue.
  5. Review the authentication settings that Claude detected, change them if needed and click Continue.
  6. Under Authentication, choose how people connect: Sign in now, Sign in when needed or No sign in.
  7. Under OAuth client, choose how Claude identifies itself. LuraDB accepts a client that registers itself at /oauth/register, so no client ID has to be prepared on the LuraDB side.
  8. Under Request headers, add a fixed credential if you do not use OAuth: the header Authorization with the value Bearer followed by the API key.
  9. Click Add.

With OAuth, go to Customize > Connectors, find the connector (usually labeled “Custom”) and click Connect to authenticate. The sign-in of LuraDB starts: you get the page shown above, type your API key and choose Allow access. To use the connector in a chat, click the + button at the lower left of the chat, then Connectors, and switch the connector on for that conversation.

Anthropic warns that custom connectors are not verified by Anthropic and that a malicious server can hide instructions in the data it returns; connect only servers you run yourself, and be careful with Allow always for tools that change data. LuraDB helps with that: keep mcp.read_only true, or give the key only the permissions the work needs.

With mcp-remote on your computer

Section titled “With mcp-remote on your computer”

For a LuraDB that Anthropic’s cloud cannot reach, for example one on 127.0.0.1, Claude Desktop can start mcp-remote, a separate open-source program that is not part of LuraDB or of Claude. It connects to the remote server and speaks to Claude Desktop over standard input and output. It needs Node.js version 18 or newer. In Claude Desktop open Settings, the Developer tab and Edit Config; the file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Add the server:

{
  "mcpServers": {
    "luradb": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:3100/mcp",
        "--allow-http",
        "--header",
        "Authorization: Bearer ${LURADB_KEY}"
      ],
      "env": { "LURADB_KEY": "lura_…" }
    }
  }
}

--allow-http lets mcp-remote use a URL without TLS; use it only for a trusted private network, and leave it out for an https:// address. The key is kept in env, as the README of mcp-remote recommends for tokens. Without --header, mcp-remote signs in with OAuth: it needs a browser on the same computer and a port on the loopback address to be redirected back to, and it keeps its credentials in ~/.mcp-auth. Quit Claude Desktop completely and start it again for the change to take effect. Then click the indicator Add files, connectors, and more / at the lower left of the chat, hover over Connectors and Manage connectors to see the tools of luradb.

An example conversation

Section titled “An example conversation”

With the tables of LuraSQL in the relational domain orders, a question in Claude Code or Claude Desktop leads to three calls of the tools of LuraDB. The wording of the exchange is an illustration; the results are the answers of a LuraDB 0.5.1 server:

You: Which orders are still open, and who placed them?


Claude  list_domains  {"engine": "rel"}
  { "domains": [ { "engine": "rel", "name": "default", "state": "active", … },
                 { "engine": "rel", "name": "orders",  "state": "active", … } ],
    "unavailable_engines": [] }


Claude  describe_table  {"domain": "orders", "table": "purchases"}
  { "name": "purchases",
    "columns": [ { "name": "id", "type": "INTEGER", "primary_key": true, … },
                 { "name": "customer_id", "type": "INTEGER", "references": "clients", … },
                 { "name": "status", "type": "TEXT", "default": "open", … },
                 { "name": "total", "type": "REAL", … }, … ],
    "indexes": [ { "column": "customer_id", "name": "purchases_customer", "unique": false } ] }


Claude  sql_query  {"domain": "orders",
                    "sql": "SELECT id, customer_id, total FROM purchases WHERE status = ?",
                    "params": ["open"], "expand": ["customer_id"]}
  { "columns": [ … ],
    "expanded": { "customer_id": [ { "email": "omar@example.com", "id": 2,
                                     "name": "Omar Haddad", "town": "Tunis", "vip": false } ] },
    "limit_applied": false, "row_count": 1, "rows": [[3, 2, 120.0]] }


Claude: One order is open: order 3 for 120.0, placed by Omar Haddad in Tunis.

The first call finds the relational domains, the second reads the columns and sees that customer_id references clients, and the third asks for the open purchases and has the server embed the client of each row through expand. All three tools only read. Every call runs with the rights of the key behind the connection, see The permissions of the key apply.

When it does not work

Section titled “When it does not work”
What you see Cause
The connection is refused or asks for authentication LuraDB answers 401: the key or the token is not accepted. Check the key, whether it was rotated, and for OAuth sign in again.
Claude Desktop cannot connect to 127.0.0.1 or a private address A custom connector connects from Anthropic’s cloud. Use a public https:// URL, or mcp-remote.
Only some tools appear mcp.read_only and mcp.allow_ddl decide which tools are offered, and a key that is not an admin sees fewer, see Tools.
A tool answers HTTP 403 Forbidden: Forbidden The key has no permission, or too low a level, on that domain.
A tool answers HTTP 428 Precondition Required The domain requires conditional writes, which MCP tools cannot send.
OAuth sign-in answers 429 Five failed sign-ins from one address within 15 minutes block that address for a while.
OAuth works, then asks again The key of the account was rotated, mcp.public_url changed, or the refresh token was used twice; sign in again.

The sign-in with OAuth and the refusals are explained on MCP server.

Sources of the Claude side

Section titled “Sources of the Claude side”

Read on 2026-11-03:

Related settings mcp.enabled · mcp.read_only · mcp.allow_ddl · mcp.oauth_enabled ·

mcp.public_url