> For the complete documentation index, see [llms.txt](https://notara.gitbook.io/notara-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://notara.gitbook.io/notara-docs/connectors/custom-http.md).

# Custom HTTP

The Custom HTTP connector lets you expose any REST API as a set of agent tools. Define endpoint paths, HTTP methods, and JSON Schema for inputs and outputs — the agent can then call your internal APIs, third-party services, or any REST endpoint as part of a conversation.

## When to Use This

Use the Custom HTTP connector when:

* You have an internal API the agent should be able to query or trigger
* You want to connect a service Notara doesn't have a built-in connector for
* You're building a proof-of-concept before writing a full MCP server

For more complex integrations with their own authentication flows, consider the [Remote MCP connector](#remote-mcp-vs-custom-http) instead.

## Setup

1. In the Notara dashboard, go to **Tools → Custom HTTP**.
2. Click **New Custom Connector**.
3. Fill in the base configuration:

| Field               | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| **Name**            | Human-readable name for this connector (e.g., "Internal API")            |
| **Base URL**        | The root URL of the API (e.g., `https://api.internal.acme.com`)          |
| **Default Headers** | Headers sent with every request (e.g., `Content-Type: application/json`) |
| **Auth Type**       | None, Bearer Token, API Key header, or Basic Auth                        |
| **Auth Value**      | Your API key or token                                                    |

4. Add tool definitions (see below).
5. Click **Save & Test** to verify the connector can reach the endpoint.

## Defining Tools

Each endpoint you want the agent to call becomes a **tool**. Click **Add Tool** to define one:

```json
{
  "name": "get_customer_health",
  "description": "Look up health score and risk flag for a customer by ID",
  "method": "GET",
  "path": "/customers/{customerId}/health",
  "capability": "read",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customerId": {
        "type": "string",
        "description": "The customer's UUID"
      }
    },
    "required": ["customerId"]
  }
}
```

For POST endpoints:

```json
{
  "name": "trigger_onboarding_email",
  "description": "Trigger the onboarding email sequence for a new user",
  "method": "POST",
  "path": "/emails/onboarding",
  "capability": "write",
  "inputSchema": {
    "type": "object",
    "properties": {
      "userId": { "type": "string" },
      "planType": { "type": "string", "enum": ["pro", "enterprise"] }
    },
    "required": ["userId", "planType"]
  }
}
```

## Capability Levels

Set `capability` to `read`, `write`, or `destructive` for each tool. This determines the default permission level:

* `read` — executes immediately
* `write` — requires admin approval
* `destructive` — admin only + in-channel confirm prompt

Use `destructive` for tools that delete data, send external notifications to many users, or make large irreversible changes.

## JSON Schema Passthrough

The `inputSchema` you define is passed through to the LLM without modification. This means you can use any valid JSON Schema, including `enum`, `anyOf`, nested objects, and `$ref` references. The agent uses the schema to construct valid requests.

The response from your API is also passed back to the agent as-is. Structure your API responses to be readable — include human-friendly field names and avoid deeply nested structures when a flat one works.

## Security Considerations

### SSRF Protection

Notara validates all base URLs at save time against an allowlist. Private IP ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.1`, `::1`) are blocked to prevent server-side request forgery attacks. Ensure your internal APIs are accessible via a public hostname or a static IP not in the private range.

### DNS Rebinding

At v1, Notara performs a URL safety check at save time and at connection time. A determined attacker who can control DNS could potentially redirect a previously safe hostname after connection. This is a known limitation for v1. If your API is sensitive, use a static IP or add your own verification at the API layer.

### Credential Security

Auth credentials (API keys, tokens) for custom HTTP connectors are encrypted at rest with AES-256-GCM, the same as all other connector credentials in Notara.

## Remote MCP vs Custom HTTP

|                  | Custom HTTP            | Remote MCP                      |
| ---------------- | ---------------------- | ------------------------------- |
| Protocol         | Plain REST             | MCP over SSE                    |
| Tool definition  | Manual JSON Schema     | Auto-discovered from MCP server |
| Auth             | API key, Bearer, Basic | Bearer token                    |
| Best for         | Simple REST endpoints  | Full-featured MCP servers       |
| Setup complexity | Low                    | Medium                          |

If the service you want to connect publishes its own MCP server (many modern dev tools do), use the Remote MCP connector type instead — it auto-discovers tools rather than requiring manual definition.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://notara.gitbook.io/notara-docs/connectors/custom-http.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.