npm package: @song-auracles/mcp
Description: MCP server for the Song Auracles API — search recordings, compositions, and projects for use with Claude, GPT, and other LLMs
Latest version: 0.1.5

# @song-auracles/mcp

Imogen MCP server for searching public and private recordings, compositions, and projects.

This package is a local stdio MCP server. In most clients, you run it directly with:

```bash
npx -y @song-auracles/mcp
```

Default API configuration:

- `IMOGEN_API_URL` defaults to `https://staging.api.auracles.io/song`
- `SA_API_KEY` is optional for public data and required for private data

## Requirements

- Node.js 18+
- `npx`

## Claude Desktop

Add this MCP server to your Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "imogen": {
      "command": "npx",
      "args": ["-y", "@song-auracles/mcp"],
      "env": {
        "SA_API_KEY": "sa_your_key_here"
      }
    }
  }
}
```

If you want to point at a different backend, add `IMOGEN_API_URL`:

```json
{
  "mcpServers": {
    "imogen": {
      "command": "npx",
      "args": ["-y", "@song-auracles/mcp"],
      "env": {
        "SA_API_KEY": "sa_your_key_here",
        "IMOGEN_API_URL": "https://your-api-domain.com"
      }
    }
  }
}
```

After saving the config, restart Claude Desktop.

## Claude Code

Add the server with the Claude CLI:

```bash
claude mcp add imogen --env SA_API_KEY=sa_your_key_here -- npx -y @song-auracles/mcp
```

With a custom backend:

```bash
claude mcp add imogen \
  --env SA_API_KEY=sa_your_key_here \
  --env IMOGEN_API_URL=https://your-api-domain.com \
  -- npx -y @song-auracles/mcp
```

Verify it:

```bash
claude mcp get imogen
```

## Codex

Add the server with the Codex CLI:

```bash
codex mcp add imogen --env SA_API_KEY=sa_your_key_here -- npx -y @song-auracles/mcp
```

With a custom backend:

```bash
codex mcp add imogen \
  --env SA_API_KEY=sa_your_key_here \
  --env IMOGEN_API_URL=https://your-api-domain.com \
  -- npx -y @song-auracles/mcp
```

Verify it:

```bash
codex mcp list
codex mcp get imogen
```

## ChatGPT

ChatGPT custom connectors use remote MCP servers over HTTP or SSE, not local stdio servers launched with `npx`.

That means this package cannot be installed into ChatGPT directly as-is.

To use Imogen with ChatGPT, you need to deploy a remote MCP server endpoint and then add that remote URL inside ChatGPT's connector settings. If you only need local MCP usage, use Claude Desktop, Claude Code, or Codex instead.

## Environment Variables

- `SA_API_KEY`: optional for public data, required for private data
- `IMOGEN_API_URL`: optional override for the API base URL

## Troubleshooting

If the server starts but tools return `404` errors:

- Check that `IMOGEN_API_URL` points to the correct backend
- The server supports both root URLs like `https://api.example.com` and versioned URLs like `https://api.example.com/v1`

If `npx` cannot launch the package:

- Confirm Node.js 18+ is installed
- Run `npx -y @song-auracles/mcp` manually to inspect startup errors

## Official MCP References

- Claude Code MCP docs: https://docs.anthropic.com/en/docs/claude-code/mcp
- Claude Desktop MCP help: https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop
- OpenAI MCP docs: https://platform.openai.com/docs/mcp
- Codex MCP docs example: https://platform.openai.com/docs/docs-mcp