> ## Documentation Index
> Fetch the complete documentation index at: https://helix-digitalocean.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Macro

> Learn how to turn any HelixQL query into an MCP endpoint using the #[mcp] macro.

## Usage

The `#[mcp]` macro enables you to expose any HelixQL query as an MCP (Model Context Protocol) endpoint, making it directly accessible to AI agents and LLM applications.

```rust theme={null}
#[mcp]
QUERY QueryName(param1: Type, param2: Type) =>
    result <- traversal_expression
    RETURN result
```

<Danger>
  You MUST only return a single object/value from the query otherwise you will get a compile error. (See [E401](../errors/E401))
</Danger>

<Warning>
  Make sure to set `mcp = true` under the instance you are using in the `helix.toml` file.
</Warning>

### How it works

When you add the `#[mcp]` attribute to a query:

1. HelixDB automatically registers the query as an MCP tool
2. The query parameters become the tool's input schema
3. The query's return type becomes the tool's output schema
4. AI agents can call this tool directly through the MCP server

<Note>
  The MCP macro automatically converts your HelixQL query into a callable MCP tool that can be used by LLM providers like OpenAI, Anthropic, and Gemini.
</Note>

***

## Using MCP Queries with LLM Providers

Once you've defined your MCP queries, you can use them with any LLM provider that supports MCP:

<CodeGroup>
  ```rust Query focus={1-2} theme={null}
  #[mcp]
  QUERY get_user(user_id: ID) =>
      user <- N<User>(user_id)
      RETURN user
  ```

  ```rust Schema theme={null}
  N::User {
      name: String,
      age: U32,
      email: String
  }
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  from helix.client import Client
  from helix.mcp import MCPServer
  from helix.providers.openai_client import OpenAIProvider
  from fastmcp.tools.tool import FunctionTool

  # Initialize MCP server
  client = Client(local=True)
  mcp = MCPServer("helix-mcp", client)

  # Add your custom tool to the MCP server
  def get_user(connection_id: str, user_id: str):
      """
      Get the name of a user by their ID
      Args: connection_id: The connection ID, user_id: The ID of the user
      Returns: The user object
      """
      return client.query(
          "mcp/get_userMcp", 
          {"connection_id": connection_id, "data":{"user_id": user_id}}
      )

  mcp.add_tool(FunctionTool.from_function(get_user))

  # Start MCP server
  mcp.run_bg()

  # Enable MCP in your LLM provider
  llm = OpenAIProvider(
      name="openai-llm",
      instructions="You are a helpful assistant with access to user data.",
      model="gpt-4o",
      history=True
  )
  llm.enable_mcps("helix-mcp")

  # The AI can now call your MCP queries
  response = llm.generate(f"What is the name of user with ID {user_id}?")
  print(response)
  ```

  ```typescript TypeScript theme={null}
  import HelixDB from "helix-ts";

  const client = new HelixDB("http://localhost:6969");

  // Add your custom MCP tool via /mcp to your MCP server
  // AI agents connected via MCP can call your queries

  // Example MCP tool call:
  const connection_id = await client.query("mcp/init", {});

  const user = await client.query("mcp/get_userMcp", {
      connection_id,
      data: {
          user_id: user_id
      }
  });
  ```

  ```bash Curl theme={null}
  # Initialize the connection, this will return a connection_id
  curl -X POST \
    http://localhost:6969/mcp/init \    
    -H 'Content-Type: application/json' \
    -d '{}'

  # Use the connection_id from above to call the MCP endpoint
  curl -X POST \
    http://localhost:6969/mcp/get_userMcp \
    -H 'Content-Type: application/json' \
    -d '{
      "connection_id": "connection_id",
      "data": {
          "user_id": "user_id"
      }
    }'
  ```
</CodeGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive query names">
    Choose query names that clearly describe what the tool does. AI agents rely on function names to understand capabilities.

    ```rust theme={null}
    // Good
    #[mcp]
    QUERY get_user_purchase_history(user_id: ID) => ...

    // Less clear
    #[mcp]
    QUERY query1(id: ID) => ...
    ```
  </Accordion>

  <Accordion title="Keep query signatures simple">
    Use clear parameter types and avoid overly complex signatures. AI agents work best with straightforward interfaces.

    ```rust theme={null}
    // Good
    #[mcp]
    QUERY search_products(name: String, max_price: F64) => ...

    // More complex - consider breaking into multiple queries
    #[mcp]
    QUERY complex_search(filters: [FilterType], options: SearchOptions) => ...
    ```
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="MCP Server Setup" href="/features/mcp/helix-mcp" icon="server">
    Learn how to set up and configure the HelixDB MCP server
  </Card>

  <Card title="MCP Guide" href="/guides/mcp-guide" icon="book">
    Complete guide for using MCP with HelixDB
  </Card>

  <Card title="Query Basics" href="/documentation/hql/hql" icon="code">
    Learn the fundamentals of writing HelixQL queries
  </Card>

  <Card title="LLM Providers" href="/documentation/sdks/helix-py#providers" icon="brain">
    Using HelixDB with different LLM providers
  </Card>
</CardGroup>