# Masheev MCP server

`@masheev/mcp` lets a compatible coding assistant discover API endpoints, inspect
schemas and execute operations. It runs as a local **stdio** process. It is not a
hosted OAuth service or an automatic workspace-provisioning wizard.

## Start with the integration skill

For an end-to-end business integration, use [Integrate with AI](https://docs.masheev.com/integrate.md).
MCP is an optional access tool within that workflow. You can implement the widget
with an existing inbox without configuring MCP.

## Configure a compatible client

Install Node.js 20 or newer. A client that accepts `mcpServers` JSON can start it
with the following process configuration; consult your client's current settings
for the file location and environment/secret mechanism.

```json
{
  "mcpServers": {
    "masheev": {
      "command": "npx",
      "args": ["-y", "@masheev/mcp"],
      "env": {
        "MASHEEV_API_BASE_URL": "https://api.masheev.com"
      }
    }
  }
}
```

Set the base URL explicitly: the package defaults to localhost. Configure secrets
through your client's supported secret/environment mechanism, not committed JSON.
Without compatible authentication, protected operations are not available.

## Authentication limitation

The current package sends `MASHEEV_API_TOKEN` as a Bearer credential. Organization
API keys are verified by the API through `X-API-Key`, while MCP spec discovery
currently checks a Better Auth session. Passing an organization API key as
`MASHEEV_API_TOKEN` does not establish the documented organization-key path.

Do not copy dashboard cookies or weaken account permissions to work around this.
Use the [supported REST key path](https://docs.masheev.com/authentication.md) or the dashboard until the
installed MCP release supports the credential you have. Confirm an organization
read before relying on provisioning access.

## Tools

| Tool | Purpose |
| --- | --- |
| `list_api_endpoints` | Find operations by text, category, tag or authentication requirement |
| `get_api_endpoint_schema` | Inspect the discovered operation |
| `execute_api_endpoint` | Call an operation with parameters |
| `get_api_categories` | List discovery categories |

Search narrowly, inspect the schema, read existing resources, then mutate only
within the requested organization and authorization. Keep returned resource IDs
so an interrupted run can resume without duplicate provisioning.

## Schema and execution limits

The current discovery parser omits request-body schemas and parameter locations.
The executor does not implement general path-parameter substitution and treats
GET/DELETE inputs as query values. For missing or complex schemas, use the full
[OpenAPI document](https://docs.masheev.com/openapi.json), then a supported API client or dashboard path.
Do not invent the omitted fields or assume every discovered endpoint is executable.

Check result content for `success: false`; an MCP transport response alone does
not prove the business operation succeeded. See [troubleshooting](https://docs.masheev.com/troubleshooting.md).