HTTP Transport

This method lets AI apps connect to Macuse over your network. It's useful for web-based AI tools or when connecting from another device.

Server Address

When you open Macuse, it automatically starts a local server at:

http://127.0.0.1:35729/mcp

You can change the address in Macuse Settings.

Authentication

Macuse uses OAuth for secure authentication. When you configure the server URL in your AI app, an authorization window will automatically appear to complete the connection.

Configuration

Add this to your AI app's configuration:

{
  "mcpServers": {
    "macuse": {
      "url": "http://127.0.0.1:35729/mcp"
    }
  }
}

After saving the configuration, your AI app will prompt you to authorize the connection.

Bearer Token Authentication

Some AI apps don't support OAuth (e.g., Cursor, Windsurf). For these apps, Macuse provides Bearer Token authentication.

How It Works

When a non-OAuth client connects to Macuse, the following happens:

1. The client attempts to connect without authentication
2. Macuse waits to see if the client initiates OAuth flow
3. After 3 failed connection attempts without starting OAuth, Macuse recognizes it as a non-OAuth client
4. A popup appears with the message: "This client doesn't support OAuth. Generate a Bearer Token instead."

The generated token is used in the Authorization header:

Authorization: Bearer <your_token>

Generating a Token

1. Configure your AI app with the Macuse server URL (without the headers field first)
2. Start your AI app and let it attempt to connect
3. After 3 failed connection attempts, Macuse will detect it doesn't support OAuth
4. A popup appears asking you to generate a token

5. Click Generate Token to create a new token
6. Copy the configuration snippet shown in the popup

7. Update your app's config file with the complete configuration including the Authorization header
8. Restart your AI app

Configuration with Bearer Token

Add this to your AI app's MCP configuration:

{
  "mcpServers": {
    "macuse": {
      "url": "http://127.0.0.1:35729/mcp",
      "headers": {
        "Authorization": "Bearer <your_token>"
      }
    }
  }
}

Replace <your_token> with the actual token from the popup (starts with mcp_).

Managing Connections

You can view and revoke connections in Macuse Settings under Connections. Each connection shows the client name, last used time, and a Revoke button.

To revoke a connection, click the Revoke button next to it. Revoked tokens immediately stop working — you'll need to trigger a new token generation by reconnecting your AI app.

Security Notes

• Tokens are stored securely — Only a hash of each token is stored in an encrypted database
• Tokens are shown once — The full token is only displayed when generated; copy it immediately
• Localhost only — The server binds to 127.0.0.1 by default, so tokens can only be used locally

Troubleshooting

Connection Refused

Make sure Macuse is running and the server is active:

1. Check the Macuse menu bar icon
2. Verify the server address in Settings matches your configuration

Invalid Token

• Verify you copied the complete token
• Check that the connection hasn't been revoked in Macuse Settings
• If the connection was revoked, remove the headers from your config and reconnect to trigger a new token generation

No Popup Appears

If Macuse doesn't prompt you to generate a token:

1. Make sure Macuse is running
2. Verify your AI app is configured with the correct server URL
3. Restart your AI app and let it retry connecting a few times
4. Check that no existing valid token is already configured