> ## Documentation Index
> Fetch the complete documentation index at: https://docs.golf.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GolfMCP quickstart

> Get started with your first GolfMCP project from scratch.

Let's get you started with your first GolfMCP project from scratch.

<Steps>
  <Step title="Install GolfMCP">
    Install the Golf MCP framework using pip:

    ```bash theme={null}
    pip install golf-mcp
    ```
  </Step>

  <Step title="Initialize your project">
    Create a new GolfMCP project using the `init` command:

    ```bash theme={null}
    golf init my_awesome_server
    cd my_awesome_server
    ```

    This will create a new directory named `my_awesome_server` with the following structure:

    ```
    my_awesome_server/
    ├── golf.json             # Main project configuration
    ├── auth.py               # Authentication configuration (new in v0.2.0)
    ├── prompts/              # Directory for prompt components
    │   └── welcome.py
    ├── resources/            # Directory for resource components
    │   ├── current_time.py
    │   └── info.py
    │   └── weather/
    │       ├── common.py
    │       ├── current.py
    │       └── forecast.py
    └── tools/                # Directory for tool components
        ├── github_user.py
        ├── hello.py
        └── payments/
            ├── charge.py
            ├── common.py
            └── refund.py
    ```

    * **`golf.json`**: Configures your server's name, port, transport, etc. (see [Configuration](/golf-mcp-framework/configuration))
    * **`auth.py`**: Dedicated file for authentication setup (see [Authentication](/golf-mcp-framework/authentication))
    * **`tools/`**, **`resources/`**, **`prompts/`**: Directories where you'll define your server's capabilities (see [Component Specification](/golf-mcp-framework/component-specification))
  </Step>

  <Step title="Set up authentication">
    The boilerplate example includes a tool that requires authentication. Golf v0.2.0 offers three authentication methods (for complete details, see [Authentication](/golf-mcp-framework/authentication)):

    <Tabs>
      <Tab title="API key authentication">
        1. **Configure API key authentication** in `auth.py`:
           ```python theme={null}
           from golf.auth import configure_api_key

           # Extract API key from Authorization header
           configure_api_key(
               header_name="Authorization",
               header_prefix="Bearer "
           )
           ```

        2. **Pass the token** when connecting your MCP client

        3. **Access the API key in your tools** using:
           ```python theme={null}
           from golf.auth import get_api_key

           api_key = get_api_key()
           ```
      </Tab>

      <Tab title="Development authentication">
        1. **Configure development tokens** in `auth.py`:
           ```python theme={null}
           from golf.auth import configure_auth, StaticTokenConfig

           configure_auth(
               StaticTokenConfig(
                   tokens={
                       "dev-token-123": {
                           "client_id": "dev-client",
                           "scopes": ["read", "write"]
                       }
                   },
                   required_scopes=["read"]
               )
           )
           ```

        2. **Use the development token** when connecting:
           ```bash theme={null}
           # Pass token via Authorization header
           Authorization: Bearer dev-token-123
           ```

        3. **No additional setup required** - perfect for development and testing
      </Tab>

      <Tab title="JWT authentication (Production)">
        1. **Set up your JWT provider** (Auth0, Okta, etc.)

        2. **Configure JWT authentication** in `auth.py`:
           ```python theme={null}
           from golf.auth import configure_auth, JWTAuthConfig

           configure_auth(
               JWTAuthConfig(
                   jwks_uri_env_var="JWKS_URI",
                   issuer_env_var="JWT_ISSUER",
                   audience_env_var="JWT_AUDIENCE",
                   required_scopes=["read:user"]
               )
           )
           ```

        3. **Set environment variables**:
           ```bash theme={null}
           JWKS_URI=https://your-provider.com/.well-known/jwks.json
           JWT_ISSUER=https://your-provider.com/
           JWT_AUDIENCE=your-api-audience
           ```

        4. **Enterprise-grade security** with standards-compliant JWT validation
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create your first tool">
    Let's modify the example "hello" tool. Open `tools/hello.py`:

    ```python theme={null}
    """Hello World tool for {{project_name}}."""

    from typing import Annotated
    from pydantic import BaseModel, Field


    class Output(BaseModel):
        """Response from the hello tool."""
        
        message: str


    async def hello(
        name: Annotated[str, Field(description="The name of the person to greet")] = "World",
        greeting: Annotated[str, Field(description="The greeting phrase to use")] = "Hello"
    ) -> Output:
        """Say hello to the given name.
        
        This is a simple example tool that demonstrates the basic structure
        of a tool implementation in GolfMCP.
        """
        # The framework will add a context object automatically
        # You can log using regular print during development
        print(f"{greeting} {name}...")
        
        # Create and return the response
        return Output(message=f"{greeting}, {name}!")

    # Designate the entry point function
    export = hello
    ```

    For more details on tool structure, parameters, and advanced patterns, see the [Component Specification](/golf-mcp-framework/component-specification).
  </Step>

  <Step title="Build for development">
    Compile your project for development:

    ```bash theme={null}
    golf build dev
    ```

    This command builds the actual MCP server.
  </Step>

  <Step title="Run your server">
    Execute the built server:

    ```bash theme={null}
    golf run
    ```

    Congratulations! You've built and run your first GolfMCP server.
  </Step>
</Steps>

## Next Steps

Now that you have a working MCP server, learn how to test it comprehensively:

* **[Test your server](/mcp-testing/getting-started/quickstart)** - Use mcp-t to validate your implementation
* **[Set up automated testing](/mcp-testing/concepts/test-suites)** - Create test suites for CI/CD
* **[Learn testing philosophy](/mcp-testing/concepts/testing-philosophy)** - Understand why traditional testing fails for MCP