# MCP Server

Sign in with your GeoDynamics account (`accounts.geodynamics.eu`) the first time your client connects. Every tool call is then scoped to the company you picked, and tools never take a `companyId` parameter. Superadmin accounts are refused here, they belong on the Admin MCP.

The Model Context Protocol server puts your own GeoDynamics data in front of an AI tool: people, clockings, timesheet totals, vehicles, and geofenced sites. Point a client at the transport URL below and the five tools appear in its tool list.

Every tool is annotated read-only. There are no write tools on this server: no clocking inserts, no timesheet approvals, no configuration changes. Reports as structured JSON are planned separately and will stay read-only as well.

## Connect your client

One transport URL serves every client: `https://mcp.geodynamics.dev/mcp`. Clients that speak remote MCP take it directly. Clients that only spawn a local process reach it through the `mcp-remote` bridge.

### Claude Desktop

Add a remote server entry that points at the hosted URL. Claude opens the GeoDynamics login in your browser the first time you connect.

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "geodynamics": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.geodynamics.dev/mcp"
      ]
    }
  }
}
```

### Cursor

Create or edit `.cursor/mcp.json` in your project, or the global Cursor MCP config, with the same remote URL.

```json title="mcp.json"
{
  "mcpServers": {
    "geodynamics": {
      "url": "https://mcp.geodynamics.dev/mcp"
    }
  }
}
```

### Any other client

Anything that can spawn a local stdio bridge reaches the same URL through `mcp-remote`.

```shell title="connect.sh"
npx -y mcp-remote https://mcp.geodynamics.dev/mcp
```

## Tools

Five tools, all reads. Company scope comes from the auth session, so no tool takes a company parameter. Ids that one tool returns are the ids the next one accepts.

TOOL [listUsers](#tool-listusers) read-only

### List users

People in your company. Start here: the `id` it returns is the `userId` that `getClockings` and `getTimesheetSummary` take.

#### Input

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `search` | string | optional | Filter by name fragment. |

#### Returns

One row per user with `id`, `name`, `code`, and `dayProgramId`.

TOOL [getClockings](#tool-getclockings) read-only

### Get clockings

Clock-in and clock-out events over a date range. Raw events, so use `getTimesheetSummary` when you need hours someone can sign off on.

#### Input

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `from` | string | required | Start of the range, ISO 8601. `2025-03-01T00:00:00Z` |
| `to` | string | required | End of the range, ISO 8601. Max 31 days. |
| `userId` | uuid | optional | One person, from `listUsers`. |

#### Returns

A `total` and the matching `items`, oldest first.

TOOL [getTimesheetSummary](#tool-gettimesheetsummary) read-only

### Get timesheet summary

Worked hours for one person over a period, straight from the post-calculation engine. These totals are the authoritative ones. Summing raw clockings yourself gives a different, wrong answer.

#### Input

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `userId` | uuid | required | From `listUsers`. |
| `from` | string | required | Start date, `YYYY-MM-DD`. |
| `to` | string | required | End date, `YYYY-MM-DD`. Max 31 days from the start. |

#### Returns

Period totals per day type, as the timesheet reports them.

TOOL [listVehicles](#tool-listvehicles) read-only

### List vehicles

Vehicles in your company that carry a tracking device.

#### Input

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `search` | string | optional | Filter by name, such as `truck` or `van 12`. |

#### Returns

One row per vehicle with `id`, `name`, and `code`.

TOOL [listPOIs](#tool-listpois) read-only

### List POIs

Geofenced locations: work sites, offices, and depots. These are the places clockings and vehicle movements are matched against.

#### Input

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `search` | string | optional | Filter by name. |

#### Returns

One row per location with its name and identifiers.

## Example prompts

Once the client is connected, ask it things like:

-   List the users in my company and show me who clocked in yesterday.
-   Give me the timesheet summary for Alice for last week.
-   Which vehicles do we have, and list our depot POIs.

## Discovery

Agents that would rather not read this page can fetch the MCP Server Card at `https://build.geodynamics.eu/.well-known/mcp/server-card.json`. It names the transport, the OAuth endpoints, and the same five tools.