# Quick Start Guide

This guide walks you through creating a real, working tool that an AI assistant can call - from zero to live in seven steps. No coding experience required for the first steps.

By the end, your AI assistant will be able to look up data or trigger an action in real time, just by understanding what a user is asking.

## Before You Start

Make sure you have:

* An MCP Functions account ([set one up here](https://docs.mcpfunctions.ai/documentation/getting-started/account-setup) if you haven't yet)
* An organization and at least one workspace created

If those words don't mean anything yet, spend two minutes on the [Introduction](https://docs.mcpfunctions.ai/documentation/getting-started/introduction) - it explains the concepts in plain language.

***

## Step 1: Create an MCP Server

Think of an MCP server as a **toolbox** - a container that holds a group of related tools and gives AI assistants one URL to connect to. You'll create one toolbox now and add tools to it.

**What to do:**

1. Open your workspace from the dashboard.
2. Click **Create MCP Server**.
3. Give it a clear name that describes what it does - for example, `Customer Support Tools` or `Order Management`.
4. Add a short description so teammates and AI assistants understand its purpose.
5. Click **Save**.

> **Why this matters:** The server name and description are shown to AI assistants when they connect. A good name helps the AI understand what kind of help this toolbox offers, so it reaches for the right tools at the right time.

{% hint style="info" %}
You can have multiple MCP servers in one workspace - for example, one for customer data, one for order management, and one for internal analytics. Each gets its own URL and authentication settings.
{% endhint %}

![Server Creation](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-1fa7290deb4a100f5f4a82f083be9f03d23ebb22%2Fqs-final-step-create-server.png?alt=media)

***

## Step 2: Configure Authentication

Once the server is created, decide how AI assistants will prove their identity when connecting to it. This is done in the **Authentication** tab of your server.

By default, the server allows unauthenticated access - which is fine for quick experimentation, but you should enable an API key for anything beyond a local test.

**What to do:**

1. Open the server you just created and click the **Authentication** tab.
2. Choose the authentication method that fits how your AI assistant connects:
   * **No Authentication** - anyone with the URL can connect. Only use this for quick local tests.
   * **API Key (Authorization Header)** - the assistant sends the key as a `Bearer` token in the request header. This is the most common option and works with all major clients.
   * **API Key (Query Parameter)** - the key is appended to the server URL. Use this when your client doesn't support custom headers.
   * **Custom Header** - you define your own header name and value. Useful for specific enterprise integrations.
3. Check your chosen method and click **Save Changes**.

> **Recommendation for most teams:** Enable **API Key (Authorization Header)**. It's the safest option and supported by ChatGPT, Claude, Cursor, and every other major MCP-compatible client.

{% hint style="info" %}
You can enable more than one method at the same time - for example, both header and query parameter - if different clients connect in different ways.
{% endhint %}

![Auth API Key](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-51f592ca8f7113068aa0ee286541e7b639836961%2Fqs-step2-authentication1.png?alt=media)

![Auth Options](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-03e9f6e76af12b2a0f964b2d51dba951083710f5%2Fqs-step2-authentication2.png?alt=media)

***

## Step 3: Create Your First Tool

A **tool** is a single function the AI can call. When a user asks something that requires real data or an action, the AI picks the right tool, sends it the right inputs, and delivers the result to the user.

You don't need to write the code yourself. Just describe what you want in plain English and the AI generates everything for you - name, description, parameters, and the full implementation.

**What to do:**

1. Open the MCP server you just created and go to the **Tools** tab.
2. Click **Create Tool**. The tool creation page opens with several sections: Basic Information, Input Parameters, Secrets & Configuration, and Implementation Code.

![Tool Basic Info](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-8469fa85ee4e70d93b1a67068d947bf34d495b8a%2Fqs-step3a-tool-form.png?alt=media)

3. **Scroll down** past the Input Parameters and Implementation Code sections until you reach the **AI Code Generation Chat** at the bottom of the page.

![AI Code Assistant](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-fc56d92caf492f8089d9b8e9f215039613ea660d%2Fqs-step3b-tool-params-code.png?alt=media)

4. In the chat input at the bottom, describe your tool in plain language. For example:

   > *"Create a tool that returns order status by order ID. The input is orderId (a string). The output should include status and updatedAt timestamp."*
5. Click **Generate Code**. The AI will search for relevant context, then fill in the tool name, description, input parameters, and the full implementation code.

![Code Generation Chat](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-4be8b332ce202472370d55ff082219e3b949d15a%2Fqs-step3d-ai-chat.png?alt=media)

6. **Scroll back up** to review what was generated:
   * **Tool Name** - the identifier used internally (e.g. `GetOrderStatus`)
   * **Description** - what the AI tells assistants this tool does; write this clearly so assistants know when to use it
   * **Input Parameters** - the fields the tool expects (e.g. `orderId`); you can add, remove, or rename these
   * **Implementation Code** - the JavaScript that runs when the tool is called; you can edit it freely
7. Make any adjustments you want, then click **Create Tool** in the top-right corner.

> **Tip for better results:** The more specific your prompt, the better the output. Mention what inputs the tool needs, what it should return, and how to handle errors - for example, *"return `{ success: false, error: 'Order not found' }` if the order ID does not exist."*

***

## Step 4: Test the Tool

Before connecting this tool to a real AI assistant, test it right here in the dashboard. You'll send it a sample input and see exactly what it returns.

**What to do:**

1. On the tool creation page, look at the **Test Tool** panel on the right side - it's always visible alongside the form.
2. Fill in the input fields with sample values - for example, enter `ORD-12345` as the order ID.
3. Click **Run Test**.
4. Review the response:
   * A green result means the tool ran successfully. Check the output looks right.
   * A red error means something went wrong. The error message will tell you what to fix.

> **What you're actually doing:** The test runs your tool in the same secure environment it will use in production. If it works here, it will work when a real AI assistant calls it.

{% hint style="success" %}
If your tool calls an external API (like your CRM or order system), it needs credentials to authenticate. That's covered in Step 5 - come back and re-test after adding your secrets.
{% endhint %}

![Tool Test Results](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-c62cfcb10758bee5a47acd6f5cfdacf8a108b505%2Fqs-step3-test-tool.png?alt=media)

***

## Step 5: Add Secrets for External APIs (If Needed)

If your tool needs to call an external service - your CRM, your database, a payment system, a third-party API - it will need credentials to authenticate. **Never put API keys directly in your tool code.** Instead, store them as workspace secrets.

Secrets are encrypted, never visible after they're saved, and automatically injected into your tool at runtime.

**What to do:**

1. Go to your **Workspace Settings** and open the **Secrets** section.
2. Click **Add Secret**.
3. Enter a name in uppercase with underscores - for example, `CRM_API_KEY` or `ORDERS_DB_TOKEN`.
4. Paste the secret value and click **Add Secret**. The value is encrypted immediately and will never be shown again.
5. Back in your tool code, access the secret like this:

   ```javascript
   const apiKey = config.CRM_API_KEY;
   ```
6. Re-run your test from Step 4 to confirm the tool works with the real credentials.

> **Why this is important:** Storing secrets separately from your code means you can safely share tool code with teammates, rotate credentials without rewriting tools, and keep production keys away from development environments.

![Workspace Secrets](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-8349a700e9bd3b1b1bb2fcd66c1936e324dd1c3c%2Fqs-step4-secrets.png?alt=media)

*Screenshot: The secrets screen. Secret names are visible but values are masked after saving. Add as many as your tools need.*

***

## Step 6: Set Up OAuth2 for External APIs (If Needed)

If your tools need to call external APIs that require an OAuth2 access token - for example, a CRM, an ERP system, or any service that uses `Authorization: Bearer <token>` - you can configure the OAuth2 connection once at the **server level** and have all tools on that server reuse it automatically.

This is more powerful than storing a static API key as a secret: OAuth2 credentials automatically fetch and refresh a token at runtime, so your tools never hold an expired token.

**What to do:**

1. Open your MCP server and click the **Settings** tab.
2. Scroll down to the **OAuth2 / External APIs** section and click **+ Add OAuth2 config**.

![OAuth2 Settings](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-4accf176d941f951d1bc7f11dd3c791744aaec37%2Fqs-step6a-oauth2-settings.png?alt=media)

3. Fill in the OAuth2 connection details:
   * **Config name** - a short identifier you'll use to reference this connection in your tool code (e.g. `myCRM`, `salesforceApi`)
   * **Token URL** - the endpoint that issues access tokens (provided by the API you're connecting to)
   * **Client ID** and **Client secret** - credentials issued to you by the external API provider
   * **Audience** and **Scope** - optional fields required by some providers to limit what the token can access
4. Click **Add**, then **Save OAuth2 settings**.

![OAuth2 Form](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-87dfb28d563ac5179441d6c4be1cb5ef3cd8fa95%2Fqs-step6b-oauth2-form.png?alt=media)

5. In your tool code, reference the config by name to get an injected token at runtime:

   ```javascript
   const token = config.myCRM; // OAuth2 access token, fetched and refreshed automatically
   const response = await fetch('https://api.mycrm.com/contacts', {
     headers: { Authorization: `Bearer ${token}` }
   });
   ```

> **Why configure OAuth2 at the server level?** Because multiple tools often call the same external API. Defining the connection once on the server means you don't repeat credentials in every tool, and rotating credentials is a single change in one place.

{% hint style="info" %}
Use **Secrets** (Step 5) for simple static API keys. Use **OAuth2** when the external API requires a short-lived token obtained through a client credentials flow.
{% endhint %}

***

## Step 7: Connect an AI Assistant

Your tool is built, tested, and ready. Now it's time to give your AI assistant access to it. Open your MCP server - the **Overview** tab shows everything you need.

**What to do:**

1. Open your MCP server. The **Overview** tab displays the server **URL** and a **Copy URL** button.
2. Click **Copy URL** to copy the server address.
3. If you enabled API key authentication in Step 2, use the key you generated at that point. The server overview does not display it again - retrieve it from the **Authentication** tab or from wherever you stored it when creating it.
4. Open your AI assistant's settings (e.g. ChatGPT, Claude, Cursor, or any other MCP-compatible client).
5. Add a new MCP server connection using the URL you copied and the API key as an `Authorization: Bearer <key>` header.
6. Save the settings and ask your assistant: *"What tools do you have available?"*

If everything is working, the assistant will list your tool by name and description - and it's ready to use.

![Server Overview](https://1140963605-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcNkjl1Dsug0KQrLLIjPR%2Fuploads%2Fgit-blob-822d7966b536b53f3827b2d7db1f43257d5e470b%2Fqs-step7-connect.png?alt=media)

> **For specific assistant setup instructions**, see [Connecting Servers](https://docs.mcpfunctions.ai/documentation/mcp-protocol/connecting-servers). It covers ChatGPT, Claude, Cursor, and others step by step.

### Controlling Which Tools a Client Can See

By default, when an assistant connects to your server it discovers **all** tools published on that server. You can restrict this using the `tools` query parameter on the server URL.

This lets you connect multiple clients or agents to the same server while giving each one access to only the tools it should use - without creating separate servers.

**How it works:**

Append `?tools=ToolName` to the server URL before handing it to a client:

```
https://server.mcpfunctions.ai/api/streamable-mcp/<server-id>/mcp?tools=GetOrderStatus
```

The client will only see and be able to call `GetOrderStatus`, even if the server has ten other tools.

You can allow multiple tools by separating names with commas:

```
https://server.mcpfunctions.ai/api/streamable-mcp/<server-id>/mcp?tools=GetOrderStatus,CreateRefund
```

**Practical examples:**

| Scenario                                         | URL                                                               |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| Customer-facing chatbot - read-only tools only   | `...?tools=GetOrderStatus,GetProductInfo`                         |
| Internal support agent - can also create tickets | `...?tools=GetOrderStatus,CreateSupportTicket,UpdateTicketStatus` |
| Admin agent - full access                        | *(no filter - connect without `?tools`)*                          |

{% hint style="info" %}
Tool names in the `tools` parameter are **case-sensitive** and must match the tool name exactly as shown in your server's Tools tab.
{% endhint %}

***

## You're Done

You've just completed your first end-to-end flow:

| What you did              | What it means                                                               |
| ------------------------- | --------------------------------------------------------------------------- |
| Created an MCP server     | Gave your tools a home that AI assistants can connect to                    |
| Configured authentication | Secured the server so only authorised assistants can connect                |
| Created a tool with AI    | Built a working function without writing code from scratch                  |
| Tested the tool           | Confirmed it runs correctly before going live                               |
| Added secrets             | Stored static credentials safely so your tools can call external APIs       |
| Set up OAuth2             | Configured token-based auth once at the server level for all tools to share |
| Connected an assistant    | Linked the AI to your tools, with optional per-client tool filtering        |

Your AI assistant can now answer real questions using live data - not just guesses.

***

## What's Next?

* [**Tutorials**](https://docs.mcpfunctions.ai/documentation/tutorials) - Follow hands-on walkthroughs for common use cases like connecting to a CRM, building a weather tool, or setting up OAuth
* [**Core Concepts**](https://docs.mcpfunctions.ai/documentation/core-concepts/platform-architecture) - Understand how organizations, workspaces, and servers fit together
* [**Creating Tools**](https://docs.mcpfunctions.ai/documentation/creating-tools/ai-powered-creation) - Go deeper on AI generation, manual coding, and advanced parameters


---

# Agent Instructions: 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:

```
GET https://docs.mcpfunctions.ai/documentation/getting-started/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.